Apache HTTP Sunucusu Sürüm 2.4 Belgeleri - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme

Apache HTTP Sunucusu Sürüm 2.4 Belgeleri

Sürümlerin Dağıtım Bilgileri

  • 2.3/2.4’deki yeni özellikler
  • Apache 2.1/2.2’deki yeni özellikler
  • Apache 2.0’daki yeni özellikler
  • 2.2’den 2.4’e yükseltme
  • Apache Lisansı

Başvuru Kılavuzu

  • Derleme ve Kurulum
  • Başlatma
  • Durdurma ve Yeniden Başlatma
  • Çalışma anı Yapılandırma Yönergeleri
  • Modüller
  • Çok Süreçlilik Modülleri (MPM’ler)
  • Süzgeçler
  • Eylemciler
  • İfade Çözümleyici
  • Sunucu ve Desteklenen Programlar
  • Terimler

Kullanıcı Kılavuzu

  • Başlarken
  • Adres ve Portları Dinleme
  • Yapılandırma Dosyaları
  • Yapılandırma Bölümleri
  • İçerik Bellekleme
  • İçerik Dili Yönetimi
  • Devingen Paylaşımlı Nesneler (DSO’lar)
  • Ortam Değişkenleri
  • Günlük Dosyaları
  • URL’lerin Dosya Sistemi ile Eşlenmesi
  • Başarım Arttırma
  • Güvenlik İpuçları
  • Sunucu Genelinde Yapılandırma
  • SSL/TLS Şifrelemesi
  • CGI için Suexec Desteği
  • mod_rewrite ile URL Yeniden Yazma Rehberi
  • Sanal Konaklar

Nasıllar ve Öğreticiler

  • Kimlik Doğrulama ve Yetkilendirme
  • Erişim Denetimi
  • CGI: Devingen İçerik
  • .htaccess dosyaları
  • Sunucu Taraflı İçerik Yerleştirme (SSI)
  • Kullanıcı Dizinleri (public_html)
  • Ters vekil yapılandırma rehberi

Platformlara Özgü Bilgiler

  • Microsoft Windows
  • RPM tabanlı Sistemler (Redhat / CentOS / Fedora)
  • Novell NetWare
  • EBCDIC Port

Diğer Konular

  • Sıkça Sorulan Sorular
  • Site Haritası
  • Geliştiriciler için Belgeler
  • Belgelendirmeye Yardım
  • Diğer Bilgiler
  • Wiki

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Upgrading to 2.4 from 2.2 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Upgrading to 2.4 from 2.2

In order to assist folks upgrading, we maintain a document describing information critical to existing Apache HTTP Server users. These are intended to be brief notes, and you should be able to find more information in either the New Features document, or in the src/CHANGES file. Application and module developers can find a summary of API changes in the API updates overview.

This document describes changes in server behavior that might require you to change your configuration or how you use the server in order to continue using 2.4 as you are currently using 2.2. To take advantage of new features in 2.4, see the New Features document.

This document describes only the changes from 2.2 to 2.4. If you are upgrading from version 2.0, you should also consult the 2.0 to 2.2 upgrading document.

See also

  • Overview of new features in Apache HTTP Server 2.4

Compile-Time Configuration Changes

The compilation process is very similar to the one used in version 2.2. Your old configure command line (as found in build/config.nice in the installed server directory) can be used in most cases. There are some changes in the default settings. Some details of changes:

  • These modules have been removed: mod_authn_default, mod_authz_default, mod_mem_cache. If you were using mod_mem_cache in 2.2, look at mod_cache_disk in 2.4.
  • All load balancing implementations have been moved to individual, self-contained mod_proxy submodules, e.g. mod_lbmethod_bybusyness. You might need to build and load any of these that your configuration uses.
  • Platform support has been removed for BeOS, TPF, and even older platforms such as A/UX, Next, and Tandem. These were believed to be broken anyway.
  • configure: dynamic modules (DSO) are built by default
  • configure: By default, only a basic set of modules is loaded. The other LoadModule directives are commented out in the configuration file.
  • configure: the "most" module set gets built by default
  • configure: the "reallyall" module set adds developer modules to the "all" set

Run-Time Configuration Changes

There have been significant changes in authorization configuration, and other minor configuration changes, that could require changes to your 2.2 configuration files before using them for 2.4.

Authorization

Any configuration file that uses authorization will likely need changes.

You should review the Authentication, Authorization and Access Control Howto, especially the section Beyond just authorization which explains the new mechanisms for controlling the order in which the authorization directives are applied.

Directives that control how authorization modules respond when they don't match the authenticated user have been removed: This includes AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative, AuthzGroupFileAuthoritative, AuthzUserAuthoritative, and AuthzOwnerAuthoritative. These directives have been replaced by the more expressive RequireAny, RequireNone, and RequireAll.

If you use mod_authz_dbm, you must port your configuration to use Require dbm-group ... in place of Require group ....

Access control

In 2.2, access control based on client hostname, IP address, and other characteristics of client requests was done using the directives Order, Allow, Deny, and Satisfy.

In 2.4, such access control is done in the same way as other authorization checks, using the new module mod_authz_host. The old access control idioms should be replaced by the new authentication mechanisms, although for compatibility with old configurations, the new module mod_access_compat is provided.

Here are some examples of old and new ways to do the same access control.

In this example, all requests are denied.

2.2 configuration:

Order deny,allow
Deny from all

2.4 configuration:

Require all denied

In this example, all requests are allowed.

2.2 configuration:

Order allow,deny
Allow from all

2.4 configuration:

Require all granted

In the following example, all hosts in the example.org domain are allowed access; all other hosts are denied access.

2.2 configuration:

Order Deny,Allow
Deny from all
Allow from example.org

2.4 configuration:

Require host example.org

Other configuration changes

Some other small adjustments may be necessary for particular configurations as discussed below.

  • MaxRequestsPerChild has been renamed to MaxConnectionsPerChild, describes more accurately what it does. The old name is still supported.
  • MaxClients has been renamed to MaxRequestWorkers, which describes more accurately what it does. For async MPMs, like event, the maximum number of clients is not equivalent than the number of worker threads. The old name is still supported.
  • The DefaultType directive no longer has any effect, other than to emit a warning if it's used with any value other than none. You need to use other configuration settings to replace it in 2.4.
  • AllowOverride now defaults to None.
  • EnableSendfile now defaults to Off.
  • FileETag now defaults to "MTime Size" (without INode).
  • mod_dav_fs: The format of the DavLockDB file has changed for systems with inodes. The old DavLockDB file must be deleted on upgrade.
  • KeepAlive only accepts values of On or Off. Previously, any value other than "Off" or "0" was treated as "On".
  • Directives AcceptMutex, LockFile, RewriteLock, SSLMutex, SSLStaplingMutex, and WatchdogMutexPath have been replaced with a single Mutex directive. You will need to evaluate any use of these removed directives in your 2.2 configuration to determine if they can just be deleted or will need to be replaced using Mutex.
  • mod_cache: CacheIgnoreURLSessionIdentifiers now does an exact match against the query string instead of a partial match. If your configuration was using partial strings, e.g. using sessionid to match /someapplication/image.gif;jsessionid=123456789, then you will need to change to the full string jsessionid.
  • mod_cache: The second parameter to CacheEnable only matches forward proxy content if it begins with the correct protocol. In 2.2 and earlier, a parameter of '/' matched all content.
  • mod_ldap: LDAPTrustedClientCert is now consistently a per-directory setting only. If you use this directive, review your configuration to make sure it is present in all the necessary directory contexts.
  • mod_filter: FilterProvider syntax has changed and now uses a boolean expression to determine if a filter is applied.
  • mod_include:
    • The #if expr element now uses the new expression parser. The old syntax can be restored with the new directive SSILegacyExprParser.
    • An SSI* config directive in directory scope no longer causes all other per-directory SSI* directives to be reset to their default values.
  • mod_charset_lite: The DebugLevel option has been removed in favour of per-module LogLevel configuration.
  • mod_ext_filter: The DebugLevel option has been removed in favour of per-module LogLevel configuration.
  • mod_proxy_scgi: The default setting for PATH_INFO has changed from httpd 2.2, and some web applications will no longer operate properly with the new PATH_INFO setting. The previous setting can be restored by configuring the proxy-scgi-pathinfo variable.
  • mod_ssl: CRL based revocation checking now needs to be explicitly configured through SSLCARevocationCheck.
  • mod_substitute: The maximum line length is now limited to 1MB.
  • mod_reqtimeout: If the module is loaded, it will now set some default timeouts.
  • mod_dumpio: DumpIOLogLevel is no longer supported. Data is always logged at LogLevel trace7.
  • On Unix platforms, piped logging commands configured using either ErrorLog or CustomLog were invoked using /bin/sh -c in 2.2 and earlier. In 2.4 and later, piped logging commands are executed directly. To restore the old behaviour, see the piped logging documentation.

Misc Changes

  • mod_autoindex: will now extract titles and display descriptions for .xhtml files, which were previously ignored.
  • mod_ssl: The default format of the *_DN variables has changed. The old format can still be used with the new LegacyDNStringFormat argument to SSLOptions. The SSLv2 protocol is no longer supported. SSLProxyCheckPeerCN and SSLProxyCheckPeerExpire now default to On, causing proxy requests to HTTPS hosts with bad or outdated certificates to fail with a 502 status code (Bad gateway)
  • htpasswd now uses MD5 hash by default on all platforms.
  • The NameVirtualHost directive no longer has any effect, other than to emit a warning. Any address/port combination appearing in multiple virtual hosts is implicitly treated as a name-based virtual host.
  • mod_deflate will now skip compression if it knows that the size overhead added by the compression is larger than the data to be compressed.
  • Multi-language error documents from 2.2.x may not work unless they are adjusted to the new syntax of mod_include's #if expr= element or the directive SSILegacyExprParser is enabled for the directory containing the error documents.
  • The functionality provided by mod_authn_alias in previous versions (i.e., the AuthnProviderAlias directive) has been moved into mod_authn_core.
  • The RewriteLog and RewriteLogLevel directives have been removed. This functionality is now provided by configuring the appropriate level of logging for the mod_rewrite module using the LogLevel directive. See also the mod_rewrite logging section.

Third Party Modules

All modules must be recompiled for 2.4 before being loaded.

Many third-party modules designed for version 2.2 will otherwise work unchanged with the Apache HTTP Server version 2.4. Some will require changes; see the API update overview.

Common problems when upgrading

  • Startup errors:
    • Invalid command 'User', perhaps misspelled or defined by a module not included in the server configuration - load module mod_unixd
    • Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration, or Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration - load module mod_access_compat, or update configuration to 2.4 authorization directives.
    • Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf - remove DefaultType and replace with other configuration settings.
    • Invalid command 'AddOutputFilterByType', perhaps misspelled or defined by a module not included in the server configuration - AddOutputFilterByType has moved from the core to mod_filter, which must be loaded.
  • Errors serving requests:
    • configuration error: couldn't check user: /path - load module mod_authn_core.
    • .htaccess files aren't being processed - Check for an appropriate AllowOverride directive; the default changed to None in 2.4.

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache HTTP Sunucusu 2.4'te Yeni olan Özellikler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTP Sunucusu 2.4'te Yeni olan Özellikler

Bu belgede Apache HTTP Sunucusunun 2.2 ve 2.4 sürümleri arasındaki başlıca farklara değinilmiştir. 2.0 sürümüne göre yeni özellikler için Apache 2.2’de Yeni olan Özellikler belgesine bakınız.

Çekirdekteki Gelişmeler

Çalışma anında yüklenebilen MPM'ler
Çok sayıda MPM artık yüklenebilir modül olarak derlenebilmektedir. Kullanılacak MPM'in seçimi çalışma anında LoadModule yönergesi üzerinden yapılabilmektedir.
Event MPM
Event MPM artık deneysel değil, ancak tam olarak desteklenmiyor.
Eşzamansıza destek
MPM'leri ve platformları desteklemek için eşzamansız okuma/yazmaya destek iyileştirildi.
Modul bazında ve dizin bazına LogLevel yapılandırması
LogLevel artık her modül ve her dizin için yapılandırılabilmektedir. debug log seviyesinin üstüne trace1'den trace8'e kadar yeni log seviyeleri eklendi.
İstek bazında yapılandırma bölümleri
<If>, <ElseIf>, ve <Else> bölümleri artık HTTP isteklerine dayalı olarak yapılandırılabilmektedir.
Genel amaçlı ifade çözümleyici
Yeni ifade çözümleyici SetEnvIfExpr, RewriteCond, Header, <If> ve benzeri yönergelerde ortak bir sözdizimi kullanarak karmaşık durumlar belirtmeyi mümkün kılmaktadır.
Milisaniye cinsinden KeepAliveTimeout
KeepAliveTimeout milisaniye cinsinden belirtmek artık mümkündür.
NameVirtualHost yönergesi
Artık gerekmemekte ve kullanımı önerilmemektedir.
Yapılandırma geçersizleştirme
Yeni AllowOverrideList yönergesi .htaccess dosyalarında kullanılabilen yönergelerde daha ince ayarlara izin vermektedir.
Yapılandırma dosyası değişkenleri
Yapılandırmada değişkenler Define yönergesi ile tanımlanabilmekte, böylece aynı değer yapılandırmada bir çok yerde kullanılıyorsa daha temiz bir görünüm elde edilebilmektedir.
Azaltılmış bellek kullanımı
Bir çok yeni özelliğe karşın, 2.4.x'te 2.2.x'e nazaran bellek kullanımı azaltılmıştır.

Yeni Modüller

mod_proxy_fcgi
mod_proxy için FastCGI Protokolü sağlayıcısı
mod_proxy_scgi
mod_proxy için SCGI Protokolü sağlayıcısı
mod_proxy_express
mod_proxy için devingen olarak yapılandırılmış tam tersinir vekiller sağlar.
mod_remoteip
İstek başlıklarında bir yük dengeleyici veya bir vekil tarafından sunulan IP adres listeli bir istek için görünen istemci IP adresi ve konak adını değiştirir.
mod_heartmonitor, mod_lbmethod_heartbeat
mod_proxy_balancer modülünün arka sunuculardaki etkin bağlantı sayısı üzerindeki yük dengeleme kararlarına dayalı işlem yapmasını sağlar.
mod_proxy_html
Başta bir üçüncü parti modüldü. Arka plandaki sağlayıcının vekil istemcileri için geçersiz URL'ler ürettiği tersinir vekil durumlarında HTML bağlarının düzeltilmesini sağlar.
mod_sed
mod_substitute modülünün geliştirilmiş hali olup yanıt gövdesinin sed'in tüm gücü ile yeniden düzenlenebilmesini sağlar.
mod_auth_form
Formlara dayalı kimlik kanıtlamayı etkinleştirir.
mod_session
Çerezleri ve veritabanı deposunu kullanarak istemciler için oturum durumunun saklanmasını etkinleştirir.
mod_allowmethods
Kimlik Doğrulama ve Yetkilendirme ile etkileşmeyen belli HTTP yöntemlerine sınır koymak için yeni bir modül.
mod_lua
Küçük iş mantıksal işlevleri ve yapılandırması için httpd içine Lua dilini gömer.
mod_log_debug
İstek işlemlerinin farklı aşamalarına özelleştirilebilir hata ayıklama günlüğü eklenmesini sağlar.
mod_buffer
Girdi ve çıktı süzgeç yığıtlarına tampon bellek sağlar.
mod_data
Yanıt gövdesini bir RFC2397 veri URL'sine dönüştürür.
mod_ratelimit
İstemciler için band genişliği oranında sınırlama sağlar.
mod_request
Kullanılabilir HTTP istek gövdelerini yapmak ve elde etmek için Süzgeçleri sağlar.
mod_reflector
Çıktı süzgeci yığıtı üzerinden bir yanıt olarak bir istek gövdesinin yansısını sağlar.
mod_slotmem_shm
Yuva temelli bir paylaşımlı bellek sağlayıcı sağlar (scoreboard olarak da bilinir).
mod_xml2enc
Başta bir üçüncü parti modüldü. libxml2 temelli süzgeç modüllerinde i18n'i destekler.
mod_macro (2.4.5'den itibaren kullanılabilir)
Yapılandırma dosyalarında makro kullanımını sağlar.
mod_proxy_wstunnel (2.4.5'den itibaren kullanılabilir)
Web-socket tünelleri için destek.
mod_authnz_fcgi (2.4.10'dan itibaren kullanılabilir)
Kimlik kanıtlama ve/veya istemcileri yetkilendirmek için FastCGI yetkilendirme uygulamalarını etkinleştirir.
mod_http2 (2.4.17'den itibaren kullanılabilir)
HTTP/2 aktarım katmanı desteği.

Modüllerdeki Gelişmeler

mod_ssl
mod_ssl bir istemci sertifikasının doğrulama durumunu sınamak için bir OCSP sunucusunu kullanmak üzere yapılandırılabilir. Öntanımlı yanıtlayıcı, istemci sertifikasının kendisinde tasarlanmış yanıtlayıcının tercih edilip edilmeyeceği kararına bağlı olarak yapılandırılabilir.
mod_ssl, ayrıca, sunucunun istemciyle anlaşma sırasında kendi sertifikasının OCSP doğrulamasını umursamazca sağlayıp aktardığı durumda OCSP zımbalamasını da destekler.
mod_ssl, sunucular arasında SSL Oturumu verisini memcached üzerinden paylaşmak üzere yapılandırılabilir.
RSA ve DSA'ya ek olarak EC anahtarları da artık desteklenmektedir.
TLS-SRP için destek (2.4.4 itibariyle kullanılabilir).
mod_proxy
ProxyPass yönergesi bir Location veya LocationMatch bloku içinde en verimli şekilde yapılandırılabilir ve büyük sayıların varlığı durumunda geleneksel iki değiştirgeli sözdiziminin de üzerinde belirgin bir başarım artışı sağlar.
Vekil istekleri için kullanılan kaynak adresi artık yapılandırılabilmektedir.
Artalanda Unix alan soketleri için destek (2.4.7 itibariyle kullanılabilir).
mod_proxy_balancer
Dengeleme yöneticisi üzerinden BalancerMembers için daha fazla çalışma anı yapılandırması
Çalışma anında dengeleme yöneticisi üzerinden başka BalancerMembers eklenebilir.
Çalışma anı yapılandırmasına yönelik dengeleyici değiştirgeleri
BalancerMembers için 'Drain' değeri belirtilebilir; böylece sadece mevcut yapışık oturumlara yanıt verirler ve bunların güzellikle hattan alınması mümkün olur.
Balancer ayarları sunucu yeniden başlatılssa bile kalıcı olabilir.
mod_cache
mod_cache CACHE süzgeci, arabellekleme üzerinde daha hassas denetim sağlamak için istenirse süzgeç zincirinin belli bir noktasına yerleştirilebilmektedir.
mod_cache artık HEAD isteklerini arabellekleyebiliyor.
Mümkün olduğunda, mod_cache yönergeleri sunucu bazında değil, dizin bazında belirtilebiliyor.
Arabellekli URL'lerin temel URL'si özelleştirilebiliyor; böylece arabelleğin bir bölümü aynı uç URL önekini paylaşabiliyor.
mod_cache, ardalanda bir sağlayıcının olmadığı durumda (5xx hatası), arabelleklenmiş bayat içeriği sunabiliyor.
mod_cache artık bir X-Cache başlığına bir HIT/MISS/REVALIDATE yerleştirebiliyor.
mod_include
Bir hata durumunda öntanımlı hata dizgisi yerine bir hata sayfası sunmayı sağlayan 'onerror' özniteliği için 'include' elemanı içinde destek.
mod_cgi, mod_include, mod_isapi, ...
Başlıkların ortam değişkenlerine dönüşümü, başlık zerki yoluyla bazı olası karşı-site-betik saldırılarının hafifletilmesinden önce daha hızlı ve doğru yapılmaktadır. Geçersiz karakterler (altçizgiler dahil) içeren başlıklar artık sessizce bırakılmaktadır.Apache'deki Ortam değişkenleri, böyle başlıkları gerektiren bozulmuş meşru istemcilerin çevresinden dolanabilen göstericilere sahiptir. (Bu durum, bu değişkenleri kullanan tüm modülleri etkiler.)
mod_authz_core Yetkilendirme Kuralları Taşıyıcıları
Gelişkin yetkilendirme kuralları artık Require yönergesi ve <RequireAll> gibi ilgili taşıyıcı yönergeler kullanılarak belirtilebilmektedir.
mod_rewrite
mod_rewrite bildik yeniden yazma senaryolarını basitleştirmek için RewriteRule yönergesine [QSD] (Query String Discard=sorgu dizgisini iptal) ve [END] seçeneklerini sağlamaktadır.
RewriteCond içinde karmaşık mantıksal ifadeler kullanımını mümkün kılmaktadır.
SQL sorgularının RewriteMap işlevleri olarak kullanılması sağlanmıştır.
mod_ldap, mod_authnz_ldap
mod_authnz_ldap kümelenmiş gruplara destek sağlar.
mod_ldap zaman aşımlarını işleme sokabilmek için LDAPConnectionPoolTTL, LDAPTimeout ve birtakım başka geliştirmeler sahiptir. Özellikle, bir LDAP sunucusunun boşta kalmış bağlantılarını bıraktıran bir durumsal güvenlik duvarı varlığında gerekli ayarlamaları yapmak için kullanışlıdır.
mod_ldap, artık, LDAP araç kiti kullanarak sağlanan hata ayıklama bilgisini günlüklemek için LDAPLibraryDebug yönergesini içermektedir.
mod_info
mod_info önceden çözümlenmiş yapılandırmayı artık sunucunun başlatılması sırasında standart çıktıya dökümleyebilmektedir.
mod_auth_basic
Temel kimlik kanıtlamayı taklit eden yeni temel mekanizma (2.4.5 itibariyle kullanılabilmektedir).

Programlardaki Gelişmeler

fcgistarter
Yeni FastCGI artalan sunucusu başlatma aracı
htcacheclean
Arabellekli URL'ler, istenirse metadata'yı da dahil ederek listelenebilmektedir.
Bazı URL'ler arabellekten tek tek silinebilmektedir.
Dosya boyutları belirtilen blok boyutuna yukarı doğru yuvarlanabilmekte, böylece dosya boyutu sınırları diskteki gerçek boyutlarla daha iyi eşlenebilmektedir.
Arabellek boyutu artık, diskteki dosyaların boyutuna göre bir sınıra ek olarak veya bunun yerine dosya düğümü sayısı ile sınırlanabilmektedir.
rotatelogs
Artık geçerli günlük dosyasına bir bağ oluşturulabiliyor.
Artık özel bir döndürme sonrası betiği çalıştırılabiliyor.
htpasswd, htdbm
Bcrypt algoritması için destek (2.4.4 itibariyle kullanılabilmektedir).

Belgelendirme

mod_rewrite
mod_rewrite belgeleri, yeniden düzenlenerek, genel kullanıma ve örneklere odaklı olarak ve diğer çözümlerin hangi durumlarda daha uygun olduğu da gösterilerek hemen hemen tamamen yeniden yazıldı. Yeniden Yazma Kılavuzu artık bir sayfa olmaktan çıkıp, çok daha ayrıntılı ve daha iyi düzenlenmiş bir bölüm haline geldi.
mod_ssl
mod_ssl belgeleri, evvelki teknik ayrıntılara ek olarak başlarken seviyesinde daha fazla örnekle büyük oranda genişletildi.
Önbellek Kullanım Kılavuzu
Önbellek Kullanım Kılavuzu mod_cache tarafından sağlanan RFC2616 HTTP/1.1 önbellekleme özellikleri arasıda daha iyi ayrım yapılabilmesi için ve socache arayüzü ile sağlanan soysal anahtar/değer önbelleklemesi yanında mod_file_cache gibi mekanizmalarla sağlanan özelleştirilebilir arabelleklemeyi de kapsamak üzere yeniden yazıldı.

Modül Geliştirici Değişiklikleri

Yapılandırma Denetleme Kancası Eklendi
Yeni bir kanca, check_config kancası, pre_config ve open_logs kancaları arasında çalışmak üzere eklendi. Ayrıca, httpd'ye -t seçeneği verildiğinde test_config kancasından önce çalışır. check_config kancası, modüllerin karşılıklı bağımlı yapılandırma yönergesi değerlerini yeniden yoklamasını ve iletiler konsola hala günlüklenebiliyorken bunların ayarlanabilmesini sağlar. Temel open_logs kanca işlevi konsol çıktısını hata günlüğüne yönlendirmeden önce hatalı yapılandırma sorunlarına karşı kullanıcı uyarılabilir.
İfade Çözümleyici Eklendi
Artık genel amaçlı bir ifade çözümleyicimiz var. API ap_expr.h içinde incelenebilir. Evvelce mod_ssl içinde gerçeklenmiş olan ifade çözümleyiciden esinlenildi.
Yetkilendirme Kuralları Taşıyıcıları
Yetkilendirme modülleri, <RequireAll> gibi gelişmiş yetkilendirme kuralı taşıyıcılarını desteklemek için ap_register_auth_provider() üzerinden artık bir sağlayıcı olarak çalıştırılabilmektedir.
Küçük Nesne Arabellekleme Arayüzü
ap_socache.h, evvelki mod_ssl oturum arabelleği gerçeklenimine dayalı olarak küçük veri nesnelerini arabelleklemek için sağlayıcı temelli bir arayüz ortaya koyar. Paylaşımlı bellek çevrimsel tamponu kullanan sağlayıcılar, disk bazlı dbm dosyaları ve memcache ile dağıtılan arabellekler şu an desteklenmektedir.
Arabellek Durum Kancası Eklendi
mod_cache modülü artık, arabellekleme kararı bilinir olduğunda çağrılan yeni bir cache_status kancası içeriyor. Öntanımlı gerçeklenim, yanıta istemlik bir X-Cache ve X-Cache-Detail ekleyebilmektedir.

Geliştirici belgeleri API değişikliklerinin ayrıntılı bir listesini içermektedir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache HTTP Sunucusu 2.2’de Yeni olan Özellikler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTP Sunucusu 2.2’de Yeni olan Özellikler

Bu belgede Apache HTTP Sunucusunun 2.0 ve 2.2 sürümleri arasındaki başlıca farklara değinilmiştir. 1.3 sürümüne göre yeni özellikler için Apache 2.0’da Yeni olan Özellikler belgesine bakınız.

Çekirdekteki Gelişmeler

Authn/Authz
Mevcut kimlik doğrulama ve yetkilendirme modüllerinin iç işleyişi yeniden düzenlendi. Yeni mod_authn_alias modülü (2.3/2.4 sürümlerinde kaldırılmıştır) belli kimlik doğrulama yapılandırmalarını büyük oranda basitleştirebilir. Bu değişikliklerin kullanıcıları ve modül yazarlarını nasıl etkilediğini öğrenmek için modül değişikliklerine ve geliştirici değişikliklerine bakabilirsiniz.
Önbellekleme
mod_cache, mod_cache_disk ve mod_mem_cache (2.3/2.4 sürümlerinde kaldırılmıştır) modüllerinde büyük oranda değişikliğe gidilerek bunlar deneysel olmaktan çıkarılıp üretim amaçlı modüller haline getirildiler. mod_cache_disk tarafından kullanılan disk alanının htcacheclean tarafından düzenli aralıklarla temizlenebilmesi sağlandı.
Yapılandırma
Öntanımlı yapılandırma basitleştirildi ve modüler bir yapıya kavuşturuldu. Sık kullanılan ortak özellikleri etkinleştirmekte kullanılan yapılandırmalar gruplanarak bunların Apache ile gelmesi ve ana sunucu yapılandırılırken yapılandırmaya kolayca eklenebilmesi sağlandı.
Nazikçe Durdurma
prefork, worker ve event MPM’leri artık httpd’yi graceful-stop sinyali sayesinde nazikçe durdurabilmektedir. httpd programının sonlandırılmasındaki gecikmelere karşı bir önlem olarak, isteğe bağlı bir zaman aşımı belirtmeyi mümkün kılan GracefulShutdownTimeout yönergesi sayesinde sunum sürüyor olsa bile httpd sonlandırılabilmektedir.
Vekil Sunucu
Yeni mod_proxy_balancer modülü ile mod_proxy için yük dengeleme hizmetleri sağlanmış, yeni mod_proxy_ajp modülü ile Apache Tomcat tarafından kullanılan Apache JServ Protokolünün 1.3 sürümü için destek eklenmiştir.
Düzenli İfade Kütüphanesi Güncellemesi
Apache, Perl uyumlu düzenli ifade kütüphanesinin 5.0 sürümünü (PCRE) içermektedir. configure betiğinin --with-pcre seçeneği sayesinde httpd programı PCRE destekli olarak derlenebilmektedir.
Akıllı Süzme
mod_filter çıktı süzgeç zincirinin devingen olarak yapılandırılmasını sağlar. Süzgeçlerin herhangi bir istek veya yanıt başlığına veya bir ortam değişkenine dayanarak koşullu olarak yerleştirilmesini mümkün kılar ve bunu yaparken 2.0 mimarisindeki sorunlu bağımlılıklar ve sıralama sorunlarının da üstesinden gelir.
Büyük Dosya (>2GB) Desteği
httpd artık günümüzün 32 bitlik Unix sistemlerinde bulunan 2 GB’lık büyük dosyaları destekleyecek tarzda derlenebilmektedir. 2 GB’lık istek gövdelerine destek de ayrıca eklenmiştir.
Event MPM
event MPM modülü sürekli bağlantı isteklerinin işlenmesi ve bağlantıların kabul edilmesi için ayrı bir evre kullanır. Sürekli bağlantı (keepalive) isteklerinin işlenmesi geleneksel olarak httpd’nin buna bir worker adamasını gerektirirdi. Bu adanmış worker bağlantı zaman aşımına uğrayıncaya değin tekrar kullanılamazdı.
SQL Veritabanı Desteği
mod_dbd modülü apr_dbd arayüzü ile birlikte, ihtiyacı olan modüllere SQL desteği sağlar. Evreli MPM’ler için bağlantı havuzlamasını destekler.

Modüllerdeki Gelişmeler

Authn/Authz
Kimlik Doğrulama, Yetkilendirme ve Erişim Denetimi ile ilgili modüller özetli kimlik doğrulamasına daha iyi destek sağlamak amacıyla yeniden isimlendirildi. Örneğin, mod_auth modülü şimdi mod_auth_basic ve mod_authn_file diye iki modüle bölünmüştür.; mod_auth_dbm modülünün ismi mod_authn_dbm ve mod_access modülünün ismi de mod_authz_host olarak değiştirilmiştir. Ayrıca, belli kimlik doğrulama yapılandırmalarını basitleştirmek üzere mod_authn_alias diye yeni bir modül vardır (2.3/2.4 sürümlerinde kaldırılmıştır).
mod_authnz_ldap
Bu modül 2.0 sürümü mod_auth_ldap modülünün 2.2 Authn/Authz arayüzüne bir uyarlamasıdır. Require yönergesine LDAP öznitelik değerlerinin ve karmaşık arama süzgeçlerinin kullanımı gibi yeni özellikler eklenmiştir.
mod_authz_owner
Dosya sistemi üzerindeki dosyalara erişimi dosya sahibine göre düzenleyebilmeyi sağlayan yeni bir modüldür.
mod_version
Çalışan sunucunun sürüm numarasına göre belli yapılandırma bloklarını etkinleştirebilen bir modüldür.
mod_info
Apache tarafından çözümlenen haliyle yapılandırma yönergelerinin gösterilmesini sağlayan yeni ?config parametresini ekler. Modül ayrıca, httpd -V’nin yaptığı gibi ek olarak derleme bilgisini ve tüm istek kancalarının sırasını da gösterir.
mod_ssl
TLS şifrelemesini HTTP/1.1 için güncelleyen RFC 2817 için destek sağlar.
mod_imagemap
mod_imap modülünün ismi yanlış anlamalara meydan vermemek için mod_imagemap olarak değiştirildi.

Programlardaki Gelişmeler

httpd
Mevcut yapılandırmaya göre yüklenen modülleri listelemek için -M diye yeni bir komut satırı seçeneği eklendi. -l seçeneğinin aksine, bu seçenekle elde edilen liste mod_so üzerinden yüklenen DSO’ları içerir.
httxt2dbm
RewriteMap yönergesinde dbm eşlem türü ile kullanmak üzere metin girdilerden DBM dosyaları üretmek için kullanılan yeni bir program.

Modül Geliştirici Değişiklikleri

APR 1.0 Programlama Arayüzü
Apache 2.2’de APR 1.0 API kullanılmıştır. Kullanımı önerilmeyen tüm işlevler ve simgeler APR ve APR-Util’den kaldırılmıştır. Ayrıntılar için APR Sitesine bakınız.
Authn/Authz
Dağıtımla gelen kimlik doğrulama ve yetkilendirme modüllerinin isimleri aşağıdaki gibi değiştirildi:
  • mod_auth_* -> HTTP kimlik doğrulamasını gerçekleştiren modüller.
  • mod_authn_* -> Kimlik doğrulamasının artalanına destek sağlayan modüller.
  • mod_authz_* -> Yetkilendirmeyi (veya erişimi) gerçekleştiren modüller.
  • mod_authnz_* -> Kimlik doğrulama ve yetkilendirmeyi birlikte gerçekleştiren modüller.
Yeni kimlik doğrulama artalanının oluşturulmasını büyük oranda kolaylaştıran yeni bir kimlik doğrulama artalanı sağlayıcı şeması vardır.
Bağlantı Hatalarının Günlüklenmesi
İstemci bağlantısında ortaya çıkan hataları günlüğe kaydetmek için ap_log_cerror isminde yeni bir işlev eklendi. Böyle bir durumda günlük kaydı istemcinin IP adresini içermektedir.
Deneme Yapılandırma Kancası Eklendi
Kullanıcı, httpd’yi sadece -t seçeneği ile kullandığı takdirde özel kod icra edilmesini isteyen modüllere yardımcı olmak üzere test_config diye yeni bir kanca işlev eklendi.
Evreli MPM’lerin Yığıt Boyutunun Ayarlanması
Tüm evreli MPM’lerin yığıt boyutunu ayarlamak üzere ThreadStackSize isminde yeni bir yönerge eklendi. Öntanımlı yığıt boyutunun küçük olduğu platformlarda bazı üçüncü parti modüller tarafından buna ihtiyaç duyulmaktadır.
Çıktı süzgeçlerinde protokoller
Evvelce her süzgeç etkilediğini yanıt başlıklarının doğru olarak üretilmesini sağlamak zorundaydı. Süzgeçler artık protokol yönetimini ap_register_output_filter_protocol veya ap_filter_protocol işlevi üzerinden mod_filter modülüne devredebilmektedir.
İzleme kancası eklendi
İzleme kancası, modüllerin ana (tepe) süreçteki sıradan/zamanlanmış işlerini yapacak modülleri etkinleştirir.
Düzenli ifade programlama aryüzü değişti
pcreposix.h başlık dosyası artık yok; yerine ap_regex.h dosyası geçti. Eski başlık dosyasınca ifade olunan POSIX.2 regex.h gerçeklenimi şimdi ap_ isim alanı altında ap_regex.h başlık dosyasındadır. regcomp, regexec gibi işlevlerin yerine de artık ap_regcomp, ap_regexec işlevleri geçerlidir.
DBD Arayüzü (SQL Veritabanı API)

Apache 1.x ve 2.0’da, modüller, SQL veritabanlarını kendileri yönetebilmek için sorumluluğu alacak bir SQL artalanına ihtiyaç duymaktadır. Her biri kendi bağlantısına sahip bir sürü modül olduğunda bu yöntem çok verimsiz olabilmektedir.

Apache 2.1 ve sonrasında veritabanı bağlantılarını (evreli olsun olmasın MPM’lerin eniyilenmiş stratejileri dahil) yönetmek için ap_dbd arayüzü kullanılmıştır. APR 1.2 ve sonrasında ise veritabanı ile etkileşim apr_dbd arayüzüyle sağlanmıştır.

Yeni modüllerin tüm SQL veritabanı işlemlerinde bu arayüzü kullanmaları ÖNERİlir. Mevcut uygulamaların uygulanabildiği takdirde hem kullanıcılarına önerilen bir seçenek olarak hem de şeffaf olarak kullanmak üzere kendilerini güncellemeleri ÖNERİir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache HTTP Sunucusu 2.0’da Yeni olan Özellikler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTP Sunucusu 2.0’da Yeni olan Özellikler

Bu belgede Apache HTTP Sunucusunun 1.3 ve 2.0 sürümleri arasındaki başlıca değişikliklerin bazılarına değinilmiştir.

Ayrıca bakınız:

  • 1.3’ten 2.0’a Yükseltme

Çekirdekteki Gelişmeler

Unix Evreleri
POSIX evreleri desteği olan Unix sistemlerinde Apache httpd, çok evreli kipte çok süreçlilik şeklinde melez bir yapıda çalışır. Bu bir çok bakımdan ölçeklenebilirliği arttırsa da bütün yapılandırmalarda sağlanamaz.
Yeni Paket Derleme Sistemi
Yeni kaynak paketi derleme sistemi autoconf ve libtool’a dayalı olarak sıfırdan, yeni baştan yazıldı. Böylece Apache httpd’nin paket yapılandırma sistemi diğer paketlerinkiyle benzerlik kazanmış oldu.
Çok Sayıda Protokol Desteği
Apache HTTP Sunucusu artık çok sayıda protokol ile hizmet sunacak bir alt yapıya sahiptir. Örneğin, mod_echo modülü bu amaçla yazılmıştır.
Unix dışı platformalara daha iyi destek
Apache HTTP Sunucusu 2.0 sürümleri, BeOS, OS/2, Windows gibi Unix olmayan platformlarda daha hızlı ve daha kararlı çalışacak duruma getirilmiştir. Genelde iyi geliştirilmemiş olan dolayısıyla istenen başarımı sağlayamayan POSIX taklit katmanlarının kullanımından vazgeçilmiş, platforma özgü çok süreçlilik modülleri (MPM) ve Apache Taşınabilirlik Arayüzü (APR) sayesinde bu platformlar artık kendi doğal programlama arayüzleriyle gerçeklenir olmuştur.
Yeni Apache httpd Programlama Arayüzü
Modüller için kullanılan programlama arayüzü 2.0 sürümüyle önemli değişikliklere uğramıştır. 1.3 sürümünde görülen modüllerle ilgili sıralama/öncelik sorunlarının çoğu giderilmiştir. 2.0 sürümü bu işlemleri daha bir özdevimli yapar olmuştur; daha fazla esneklik sağlamak için artık kancalı modül sıralaması kullanılabilmektedir. Ayrıca, arayüze, Apache HTTP Sunucususu çekirdeğini yamamaya gerek kalmadan modüllerle sunucu yeteneklerinin arttırılabilmesini sağlayan yeni çağrılar eklenmiştir.
IPv6 Desteği
IPv6’nın Apache Taşınabilirlik Arayüzü kütüphanesi tarafından desteklendiği sistemlerde Apache httpd öntanımlı olarak IPv6 soketlerini dinler. Bundan başka, Listen, NameVirtualHost ve VirtualHost yönergelerinin IPv6 sayısal adres dizgelerini desteklemesi sağlanmıştır.
Örnek: Listen [2001:db8::1]:8080
Süzme
Apache httpd modülleri, artık, sunucuya teslim edilen veya sunucudan teslim alınan içerik akımları üzerinde süzgeç gibi davranacak şekilde yazılabilmektedir. Bu sayede, örneğin CGI betiklerinin çıktılarının mod_include modülünün INCLUDES süzgeci kullanılarak SSI yönergeleri için çözümlenmesi mümkündür. CGI programlarının birer eylemci olarak davranması gibi, mod_ext_filter modülü de harici programların birer süzgeç olarak davranabilmesini mümkün kılar.
Çok Dilli Hata Yanıtları
Hata yanıtlarının tarayıcılara yönelik iletileri artık SSI belgeleri kullanılarak çeşitli dillerde sağlanabilmektedir. Bunlar ayrıca yönetici tarafından görünüş ve kullanışlılık tutarlılığı bakımından kişiselleştirilebilmektedir.
Basitleştirilmiş Yapılandırma
Bazı yönergelerle ilgili kafa karışıklıkları giderilmiştir. Bilhassa belli bir IP adresini dinlemek için kullanılan Port ve BindAddress yönergeleri ile ilgili karışıklığın önüne geçmek için sadece Listen yönergesi yeterli olmaktadır. ServerName yönergesi ise sadece yönlendirme ve sanal konak tanıma amacıyla sunucu ismi ve port belirtiminde kullanılmaktadır.
Doğal Windows NT Unicode Desteği
Apache httpd 2.0, Windows NT üzerinde artık tüm dosya sistemi kodlamalarında utf-8 kullanmaktadır. Bu destek, Windows 2000 ve Windows XP dahil tüm Windows NT temelli sistemlere çok dillilik desteğini sağlamak üzere mevcut Unicode dosya sistemine doğrudan uyarlanır. Dosya sisteminde makinenin yerel karakter kodlamasını kullanan kullanan Windows 95, 98 ve ME için bu destek yoktur.
Düzenli İfade Kütüphanesi Güncellemesi
Apache httpd 2.0’da Perl uyumlu düzenli ifade kütüphanesi bulunur. Tüm düzenli ifadelerde artık çok daha güçlü olan Perl 5 sözdizimi kullanılmaktadır.

Modüllerdeki Gelişmeler

mod_ssl
Apache httpd 2.0’da yeni olan bu modül, OpenSSL tarafından sağlanan SSL/TLS şifreleme protokollerine bir arayüzdür.
mod_dav
Apache httpd 2.0’da yeni olan bu modül, site içeriğinin destek ve bakımı için HTTP dağıtık yazım ve sürüm yönetimi (DAV - Distributed Authoring and Versioning) belirtimini gerçekler.
mod_deflate
Apache httpd 2.0’da yeni olan bu modül sayesinde ağ band genişliğinden daha verimli yararlanabilmek için içeriğin sıkıştırılarak gönderilmesini talep eden tarayıcıların desteklenmesi mümkün olmuştur.
mod_auth_ldap
Apache httpd 2.0.41’de yeni olan bu modül, HTTP temel kimlik doğrulamasında kullanılan delillerin saklanması için LDAP veritabanının kullanılabilmesini mümkün kılar. Kardeş modülü olan mod_ldap ise bağlantı havuzlaması ve sonuçların önbelleğe alınması ile ilgilenir.
mod_auth_digest
Paylaşımlı belleği kullanan süreçlere karşı oturum önbelleklemesi için ek destek içerir.
mod_charset_lite
Apache httpd 2.0’da yeni olan bu deneysel modül, karakter kümesi dönüşümleri veya kaydı için destek sağlar.
mod_file_cache
Apache httpd 2.0’da yeni olan bu modül, Apache HHP Sunucusu 1.3’teki mod_mmap_static modülünün işlevselliğini içermenin yanında buna önbellekleme yetenekleri de ekler.
mod_headers
Bu modül Apache httpd 2.0’da daha esnek hale getirilmiştir. Artık mod_proxy tarafından kullanılan istek başlıkları değiştirilebilmekte ve bunlar yanıt başlıklarına şartlı olarak atanabilmektedir.
mod_proxy
Bu modül HTTP/1.1 uyumlu vekaleti daha güvenilir kılmak ve yeni süzgeç alt yapısının getirilerinden de yararlanmak amacıyla yeni baştan yazılmıştır. Bunun yanında, <Proxy> bölümünün yeni hali vekil siteleri desteklemek bakımından daha okunabilir (ve kendi içinde daha hızlı) olması sağlanmıştır; <Directory "proxy:..."> yapılandırması artık desteklenmemektedir. Modül, proxy_connect, proxy_ftp ve proxy_http şeklinde her biri belli bir protokolü destekleyen ayrı modüllere bölünmüştür.
mod_negotiation
Yeni ForceLanguagePriority yönergesi sayesinde istemciye “Kabul edilebilir bir gösterim çeşidi yok” ya da “Çok sayıda seçim belirtilmiş” yanıtını döndürmek yerine tüm durumlara uyan bir sayfanın gönderilebilmesi sağlanmıştır. Bundan başka, uzlaşım ve MultiViews algoritmaları daha tutarlı sonuçlar elde etmek amacıyla elden geçirilmiş ve belge içeriği ile daha iyi eşleşen yeni bir tür eşlem yapısı sağlanmıştır.
mod_autoindex
Dizin içeriklerinin özdevimli listelenmesi artık HTML tabloları kullanılacak şekilde yapılandırılabilmektedir. Böylece sayfa daha iyi biçemlenebilmekte, içerik daha hassas sıralanabilmekte, sürüm numarasına göre sıralama yapılabilmekte ve dosya ismi kalıpları kullanılarak sadece istenen içerik listelenebilmektedir.
mod_include
Yeni yönergeler, değiştirilecek SSI elemanları için öntanımlı başlangıç ve bitiş etiketlerine izin vermekte, hataların ve zaman biçemleme yapılandırmalarının SSI belgesinde değil ana yapılandırma dosyasında bulunması mümkün olmaktadır. Düzenli ifadelerin gruplanmış sonuçları (Perl düzenli ifade sözdizimi kullanılmaktadır) mod_include modülünün $0 .. $9 değişkenleri sayesinde kullanılabilmektedir.
mod_auth_dbm
AuthDBMType yönergesi sayesinde artık çok sayıda DBM tarzı veritabanı türü desteklenmektedir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


The Apache License, Version 2.0 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

The Apache License, Version 2.0

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions

    "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

    "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

    "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
    1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
    2. You must cause any modified files to carry prominent notices stating that You changed the files; and
    3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
    4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


Derleme ve Kurulum - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Derleme ve Kurulum

Bu belge Apache HTTP Sunucusunun sadece Unix ve Unix benzeri sistemlerde derlenmesini ve kurulmasını kapsar. Windows üzerinde derleme ve kurulum için Apache HTTP Sunucusunun Microsoft Windows ile kullanımı ve Apache HTTP Sunucusunun Microsoft Windows için Derlenmesi bölümüne bakınız. Diğer platformlar için ise platform belgelerine bakınız.

Apache HTTP Sunucusunun, derleme ortamını oluşturmak için çoğu Açık Kaynak Kodlu projenin yaptığı gibi libtool ve autoconf kullanır.

Eğer sadece sürüm yükseltiyorsanız (2.4.9’dan 2.4.10’a yükseltmek gibi) lütfen doğrudan Yükseltme bölümüne atlayınız.

Ayrıca bakınız:

  • Kaynak ağacının yapılandırılması
  • Apache httpd’nin başlatılması
  • Durdurma ve yeniden başlatma

Tez canlılar için genel bir bakış

İndirme | $ lynx http://httpd.apache.org/download.cgi
Paketi açma $ gzip -d httpd-NN.tar.gz
$ tar xvf httpd-NN.tar
$ cd httpd-NN
Yapılandırma | $ ./configure --prefix=ÖNEK
Derleme | $ make
Kurulum | $ make install
Kişiselleştirme | $ vi ÖNEK/conf/httpd.conf
Deneme | $ ÖNEK/bin/apachectl -k start

NN yerine kuracağınız sürümü, ÖNEK yerine de dosya sisteminde sunucunun altına kurulacağı dizin yolunu yazınız. ÖNEK belirtilmezse /usr/local/apache2 öntanımlıdır.

Derleme ve kurulum işleminin her aşaması, Apache HTTPd Sunucusunun derlenmesi ve kurulması için gerekenler başta olmak üzere aşağıda ayrıntılı olarak açıklanmıştır.

Gereksinimler

Apache httpd’yi derleyebilmek için şunlar mevcut olmalıdır:

APR ve APR-Util
APR ve APR-Util'in sisteminizde kurulu olduğundan emin olun. Kurulu değilse veya sisteminizce sağlanmış sürümlerini kullanmak istemiyorsanız APR ve APR-Util'in ikisini birden Apache APR'den indirin ve onları Apache httpd dağıtımını açtığınız dizinin altında /httpd_kaynakkod_kök_dizini/srclib/apr ve /httpd_kaynakkod_kök_dizini/srclib/apr-util dizinlerine açın (Dizin isimlerinin sürüm numarası içermemesine dikkat edin, örneğin, APR dağıtımı /httpd_kaynakkod_kök_dizini/srclib/apr/ altında olsun.) ve ./configure betiğinin --with-included-apr seçeneğini kullanın. Bazı platformlarda, httpd'nin, kurulu APR ve APR-Util kopyanıza karşın derlenmesini sağlamak için ilgili -dev paketlerini kurmanız gerekebilir.
Perl-Uyumlu Düzenli İfade Kütüphanesi (PCRE)
Bu kütüphane gereklidir, ancak artık httpd ile birlikte dağıtılmamaktadır. Kaynak kodunu http://www.pcre.org sitesinden indirin ve bir port veya paket olarak kurun. Eğer derleme sisteminiz PCRE kurulumunuz tarafından kurulan pcre-config betiğini bulamazsa --with-pcre seçeneğini kullanarak yerini belirtin. Bazı platformlarda, httpd'nin, kurulu PCRE kopyanıza karşın derlenmesini sağlamak için ilgili -dev paketlerini kurmanız gerekebilir.
Disk Alanı
Geçici olarak en azından 50 MB boş disk alanınız olduğundan emin olunuz. Kurulumdan sonra sunucu yaklaşık 10 MB disk alanı kaplıyor olacaktır. Asıl disk alanı gereksinimi seçtiğiniz yapılandırma seçeneklerine, üçüncü parti modüllere ve şüphesiz sitenizin veya sunucu üzerindeki sitelerin boyutlarına göre değişiklik gösterecektir.
ANSI-C Derleyici ve Derleme Sistemi
Bir ANSI-C derleyicinin kurulu olduğundan emin olunuz. Free Software Foundation (FSF) tarafından dağıtılan GNU C derleyicisini (GCC) kullanmanız önerilir. GCC yoksa en azından satıcınızın derleyicisinin ANSI uyumlu olduğundan emin olunuz. Ayrıca, PATH ortam değişkeninizin içerdiği yollarda make gibi temel derleme araçları da bulunmalıdır.
Zamanın doğru belirlenmesi
HTTP protokolünün elemanları sunuldukları tarih ve saate göre ifade edilirler. Bu bakımdan sisteminizdeki zaman ayarlama oluşumunun ayarlarını gözden geçirmenizin tam sırasıdır. Bu amaçla, Ağ Zaman Protokolüne (NTP) göre çalışan ntpdate veya xntpd programları kullanılır. NTP yazılımları ve halka açık zaman sunucuları hakkında daha ayrıntılı bilgi için NTP sitesine bakınız.
Perl 5 [SEÇİMLİK]
Perl ile yazılmış apxs veya dbmmanage gibi bazı betikleri desteklemek için Perl 5 yorumlayıcısı gerekir (5.003 veya daha yeni sürümleri yeterlidir). Eğer configure betiği sisteminizde Perl 5 yorumlayıcısı bulamazsa bu betikleri kullanamazsınız. Ancak, bu durum Apache HTTPd’nin derlenip kurulmasına engel değildir.

İndirme

Apache HTTP Sunucusunu, çeşitli yansıların da listelendiği Apache HTTP Sunucusu indirme sayfasından indirebilirsiniz. Unix benzeri sistemler kullanan Apache HTTPd kullanıcılarının kaynak paketlerinden birini indirip derlemeleri daha iyi olacaktır. Derleme işlemi (aşağıda açıklanmıştır) kolaydır ve sunucunuzu ihtiyaçlarınıza uygun olarak kişiselleştirmenize imkan tanır. Ayrıca, hazır derlenmiş paketler çoğunlukla en son kaynak sürüm kadar güncel değildirler. Eğer böyle bir paket indirmişseniz, kurarken paketin içinde bulunan INSTALL.bindist dosyasındaki talimatlara uyunuz.

İndirme işleminin ardından Apache HTTP Sunucusunun eksiksiz ve değişikliğe uğramamış olduğunun doğrulanması önemlidir. Bu indirilen tar paketinin PGP imzasına göre sınanması ile sağlanabilir. Bunun nasıl yapılacağı indirme sayfasında anlatıldığı gibi PGP kullanımının anlatıldığı daha geniş bir örnek de vardır.

Paketi açma

Apache HTTP Sunucusu tar paketinden sıkıştırmayı kaldırdıktan sonra tar arşivinden dosyaları çıkarmak basit bir işlemdir:

$ gzip -d httpd-NN.tar.gz
$ tar xvf httpd-NN.tar

Bu işlem bulunduğunuz dizinin içinde dağıtımın kaynak dosyalarını içeren yeni bir dizin oluşturacaktır. Sunucuyu derleme işlmine başlayabilmek için önce cd ile bu dizine geçmelisiniz.

Kaynak ağacının yapılandırılması

Sonraki adım, Apache HTTPd kaynak ağacının platformunuza ve kişisel gereksinimlerinize uygun olarak yapılandırılmasıdır. Bu işlem dağıtımın kök dizininde bulunan configure betiği kullanılarak yapılır. (Apache HTTPd kaynak ağacının resmen dağıtıma girmemiş bir sürümünü indiren geliştiricilerin sistemlerinde autoconf ve libtool kurulu olması ve sonraki adıma geçmek için buildconf çalıştırmaları gerekir. Bu işlem resmi dağıtımlar için gerekli değildir.)

Kaynak ağacını tamamen öntanımlı seçenekler kullanılarak derlemek için ./configure komutunu vermek yeterlidir. Öntanımlı seçenekleri değiştirmek için configure betiği çeşitli değişkenler ve komut satırı seçenekleri kabul eder.

En önemli seçenek, Apache HTTP Sunucusunun kurulacağı yerin belirlenmesini, dolayısıyla Apache’nin bu konumda doğru olarak çalışması için yapılandırılmasını sağlayan --prefix’tir. Kurulacak dosyaların yerleri ile ilgili daha ayrıntılı denetim ek yapılandırma seçenekleri ile mümkün kılınmıştır.

Bu noktada ayrıca, Apache HTTPd’de hangi özelliklerin bulunmasını istediğinizi modülleri etkin kılarak veya iptal ederek belirtebilirsiniz. Apache, öntanımlı olarak içerilmiş pek çok modülle gelir. Bunlar çalışma anında devereye sokulup çıkarılabilen paylaşımlaı nesneler (DSO'lar) olarak derlenebilir. Ayrıca, istediğiniz modülleri derleme sırasında --enable-module=static seçeneğini kullanarak durağan olarak derleyebilirsiniz. Ek modüller --enable- modül seçenekleri kullanılarak etkinleştirilir. Buradaki modül, önünden mod_ dizgesi kaldırılmış ve içindeki altçizgi imleri tire imleri ile değiştirilmiş modül ismidir. Temel modülleri de benzer şekilde --disable-modül seçenekleriyle iptal edebilirsiniz. configure betiği mevcut olmayan modüller için sizi uyarmayıp, seçeneği yok saymakla yetineceğinden, bu seçenekleri kullanırken dikkatli olmalısınız.

Ek olarak, bazen kullandığınız derleyici, kütüphaneler veya başlık dosyalarının yerleri hakkında configure betiğine ilave bilgiler sağlamanız gerekir. Bu işlem configure betiğine ya ortam değişkenleriyle ya da komut satırı seçenekleriyle bilgi aktarılarak yapılır. Daha fazla bilgi için configure kılavuz sayfasına bakınız.

Apache’yi derlerken ne gibi olasılıklara sahip olduğunuz hakkında bir izlenim edinmeniz için aşağıda tipik bir örneğe yer verilmiştir. Bu örnekte, Apache’nin /sw/pkg/apache önekiyle başlayan dizinlere kurulması, belli bir derleyici ve derleyici seçenekleriyle derlenmesi ve mod_ldap ve mod_luamodüllerinin de DSO mekanizması üzerinden daha sonra yüklenmek üzere derlenmesi istenmektedir:

$ CC="pgcc" CFLAGS="-O2" \
./configure --prefix=/sw/pkg/apache \
--enable-ldap=shared \
--enable-lua=shared

configure betiği başlatıldığında sisteminizde mevcut özelliklerin işe yararlığını sınamak ve sonradan sunucuyu derlemek için kullanılacak Makefile dosyalarını oluşturmak için bir kaç dakika çalışacaktır.

configure seçeneklerinin tamamı ayrıtılı olarak configure kılavuz sayfasında açıklanmıştır.

Derleme

Artık, Apache HTTPd paketini şekillendiren çeşitli parçaları derlemek için basitçe aşağıdaki komutu verebilirsiniz:

$ make

Bu komutu verdikten sonra lütfen sabırlı olunuz. Temel yapılandırmanın derlenmesi bir kaç dakika alsa da modüllerin derlenmesi donanımınıza ve seçtiğiniz modüllerin sayısına bağlı olarak daha uzun süre gerektirecektir.

Kurulum

Şimdi sıra ÖNEK dizini altına kurulmak üzere yapılandırdığınız (yukarı --prefix seçeneğine bakınız) paketi kurmaya geldi. Basitçe şu komutu veriniz:

# make install

ÖNEK dizininde genellikle yazma izinlerinin sınırlı oluşu nedeniyle bu adım genellikle root yetkilerini gerektirir.

Eğer sürüm yükseltiyorsanız, kurulum sırasında mevcut yapılandırma dosyalarının ve belgelerin üzerine yazılmayacaktır.

Kişiselleştirme

Bu adımda, Apache HTTP Sunucunuzu ÖNEK/conf/ dizini altındaki yapılandırma dosyalarını düzenleyerek kişiselleştirebilirsiniz.

$ vi ÖNEK/conf/httpd.conf

Bu kılavuz ve kullanılabilecek yapılandırma yönergelerinin kılavuzlarını ÖNEK/docs/manual/ altında bulabileceğiniz gibi en son sürümünü daima http://httpd.apache.org/docs/2.4/ adresinde bulabilirsiniz.

Deneme

Artık Apache HTTP Sunucunuzu başlatmaya hazırsınız. Hemen şu komutu verin:

$ ÖNEK/bin/apachectl -k start

http://localhost/ üzerinden ilk belgeniz için bir istek yapmalısınız. Genellikle DocumentRoot olarak bilinen ÖNEK/htdocs/ altındaki sayfayı görürsünüz. Çalışmakta olan sunucuyu durdurmak için şu komutu verebilirsiniz:

$ ÖNEK/bin/apachectl -k stop

Yükseltme

Sürüm yükseltme işleminin ilk adımı, sitenizi etkileyen değişiklikleri öğrenmek için dağıtım duyurusunu ve kaynak paketindeki CHANGES dosyasını okumaktır. Ana sürümlerden yükseltme yapıyorsanız (2.0’ten 2.2’ye veya 2.2’den 2.4’e gibi), derleme anı ve çalışma anı yapılandırmalarındaki ana farklılıklar elle ayarlamalar yapmanızı gerektirecektir. Ayrıca, tüm modüllerin de modül API’sindeki değişikliklere uyum sağlaması için yükseltilmesi gerekecektir.

Aynı ana sürüm içinde yükseltme yapmak (2.2.55’ten 2.2.57’ye yükseltmek gibi) daha kolaydır. make install işlemi, mevcut yapılandırma ve günlük dosyalarınızın ve belgelerin üzerine yazmayacaktır. Ek olarak, geliştiriciler alt sürüm değişikliklerinde configure seçenekleri, çalışma anı yapılandırması veya modül API’sinde uyumsuz değişiklikler yapmamaya özen göstereceklerdir. Çoğu durumda, aynı configure komut satırını, aynı yapılandırma dosyasını kullanabileceksiniz ve tüm modülleriniz de çalışmaya devam edebilecektir.

Aynı ana sürüm içinde yükseltme işlemine, eski kaynak ağacının kök dizininde veya kurulu sunucunuzun build dizininde bulacağınız config.nice dosyasını yeni kaynak ağacının kök dizinine kopyalamak suretiyle başlayabilirsiniz. Bu dosya evvelce kaynak ağacını yapılandırmakta kullandığınız configure komut satırını içerir. config.nice dosyasında yapmak istediğiniz değişiklikler varsa yaptıktan sonra şu komutları veriniz:

$ ./config.nice
$ make
$ make install
$ ÖNEK/bin/apachectl -k graceful-stop
$ ÖNEK/bin/apachectl -k start

Her yeni sürümü hizmete sokmadan önce daima çalışma ortamınızda denemeniz gerekir. Örneğin, yükseltme işlemini sonuçlandırmadan önce eski sürümün çalışmasını durdurmadan yenisini farklı bir --prefix ile kurabilir ve farklı bir port ile (Listen yönergesini ayarlamak suretiyle) çalıştırabilirsiniz.

Özgün configure seçeneklerinizi değiştirmek veya yeni seçenekler eklemek isterseniz bunları config.nice betiğine komut satırı argümanları olarak belirtebilirsiniz:

$ ./config.nice --prefix=/home/dnm/apache --with-port=90

Üçüncü parti paketler

Üçüncü partilerin çoğunun, Apache HTTP Sunucusunun belli bir platforma kurulumu için paketlenmiş kendi dağıtımları vardır. Çeşitli Linux dağıtımları, üçüncü parti Windows paketleri, Mac OS X, Solaris ve daha pek çokları bunlar arasında sayılabilir.r

Yazılım lisansımız bu çeşit yeniden dağıtımlara izin verdiği gibi bunları cesaretlendirir de. Ancak, sunucunun kurulum ve yapılandırmasının belgelerimizde belittiğimizden farklı olması gibi bir durum ortaya çıkabilir. Ne yazık ki, bu durum yakın zamanda değişecekmiş gibi görünmüyor.

Bu üçüncü parti dağıtımlarla ilgili bir açıklamaya HTTP Sunucu wikisinde yer verilmiş olup bunların şu anki durumunu yansıtmaktadır. Ancak, yine de, dağıtımınızın belli platformlarla ilgili paket yönetimi ve kurulum işlemleri hakkında bilgi sahibi olmanız gerekmektir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache HTTPd’nin başlatılması - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTPd’nin başlatılması

Apache normal olarak, Windows'ta bir hizmet olarak çalışır. Ayrıntılı bilgi için Apache HTTPD’nin bir hizmet olarak çalıştırılması bölümüne bakınız.

Unix’te ise artalanda isteklere yanıt vermek için sürekli çalışan bir artalan sürecidir. Bu belgede httpd’nin nasıl çalıştırılacağı açıklanmaktadır.

Ayrıca bakınız:

  • Durdurma ve Yeniden Başlatma
  • httpd
  • apachectl

Apache Nasıl Başlatılır?

Yapılandırma dosyasında Listen yönergesi ile öntanımlı olan port 80 (veya 1024’ten küçük herhangi bir port) belirtilmişse Apache HTTP Sunucusunu başlatmak için root yetkileri gerekecektir. Sunucu başlatılıp günlük dosyalarını açmak gibi bazı ön hazırlık etkinliklerinde bulunduktan sonra istemcilerden gelen istekleri dinlemek ve yanıt vermek için çeşitli çocuk süreçler başlatır. Ana httpd süreci root kullanıcısının aidiyetinde çalışmasını sürdürürken çocuk süreçler daha az yetkili bir kullanıcının aidiyetinde çalışır. Bu işlem seçilen Çok Süreçlilik Modülü tarafından denetlenir.

httpd’yi çalıştırmak için önerilen yöntem apachectl betiğini kullanmaktır. Bu betik, httpd’nin bazı işletim sistemlerinde işlevini gerektiği gibi yerine getirebilmesi için gereken belli ortam değişkenlerini ayarlar ve httpd’yi çalıştırır. apachectl, komut satırı argümanlarını httpd’ye aktarabildiğinden gerekli httpd seçenekleri apachectl betiğine komut satırı seçenekleri olarak belirtilebilir. Ayrıca, apachectl betiğinin içeriğini doğrudan düzenlemek suretiyle betiğin başlangıç satırlarındaki HTTPD değişkenine httpd çalıştırılabilir dosyasının doğru yerini ve daima mevcut olmasını istediğiniz komut satırı seçeneklerini belirtebilirsiniz.

httpd çalıştırıldığında yaptığı ilk şey yapılandırma dosyası httpd.conf’u bulup okumaktır. Bu dosyanın yeri derleme sırasında belirtilmekteyse de -f komut satırı seçeneği kullanılarak çalıştırma sırasında belirtmek de mümkündür:

/usr/local/apache2/bin/apachectl -f /usr/local/apache2/conf/httpd.conf

Başlatma sırasında herşey yolunda giderse sunucu kendini uçbirimden ayıracak ve hemen ardından uçbirim, komut istemine düşecektir. Bu, sunucunun etkin ve çalışmakta olduğunu gösterir. Artık tarayıcınızı kullanarak sunucuya bağlanabilir ve DocumentRoot dizinindeki deneme sayfasını görebilirsiniz.

Başlatma Sırasındaki Hatalar

Apache başlatma sırasında ölümcül bir sorunla karşılaşacak olursa çıkmadan önce sorunu açıklayan bir iletiyi konsola veya ErrorLog yönergesi ile belirtilen hata günlüğüne yazacaktır. En çok karşılaşılan hata iletilerinden biri "Unable to bind to Port ..." dizgesidir. Bu iletiye genellikle şu iki durumdan biri sebep olur:

  • Sunucunun, root yetkileri gerektiren bir portu kullanmak üzere root kullanıcısı tarafından çalıştırılmamış olması.
  • Aynı portu kullanan başka bir Apache Sunucusunun veya başka bir HTTP sunucusunun zaten çalışmakta oluşu.

Bu ve diğer sorun çözme talimatları için Apache SSS’sini inceleyiniz.

Sistem Açılışında Başlatma

Sunucunuzun sistem yeniden başlatıldıktan sonra çalışmasına devam etmesini istiyorsanız sistem başlatma betiklerinize (genellikle ya rc.local dosyasıdır ya da bir rc.N dizininde bir dosyadır) apachectl betiği için bir çağrı eklemelisiniz. Bu, Apache sunucunuzu root yetkileriyle başlatacaktır. Bunu yapmadan önce sunucunuzun güvenlik ve erişim kısıtlamaları bakımından gerektiği gibi yapılandırıldığından emin olunuz.

apachectl betiği, bir standart SysV init betiği gibi davranacak şekilde tasarlanmıştır. start, restart ve stop argümanlarını kabul edebilir ve bunları httpd’ye uygun sinyallere dönüştürebilir. Bu bakımdan, çoğunlukla uygun init dizinlerinden birine apachectl betiği için basitçe bir bağ yerleştirebilirsiniz. Fakat bunu yapmadan önce betiğin sisteminizin gereklerini yerine getirdiğinden emin olunuz.

Ek Bilgiler

httpd, apachectl ve sunucuyla gelen diğer destek programlarının komut satırı seçenekleri hakkında ek bilgi Sunucu ve Destek Programları sayfasında bulunabilir. Ayrıca, Apache dağıtımında bulunan tüm modüller ve bunlarla sağlanan yönergeler hakkında da belgeler vardır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache HTTP Sunucusunun Durdurulması ve Yeniden Başlatılması - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTP Sunucusunun Durdurulması ve Yeniden Başlatılması

Bu belge Apache HTTP Sunucusunun Unix benzeri sistemlerde durdurulması ve yeniden başlatılması konularını kapsar. Windows NT, 2000 ve XP kullanıcıları Apache HTTPd’yi bu platformlarda nasıl denetimlerine alacaklarını öğrenmek için httpd’nin Bir Hizmet Olarak Çalıştırılması sayfasına, Windows 9x ve ME kullanıcıları ise httpd’nin Bir Konsol Uygulaması Olarak Çalıştırılması sayfasına bakabilirler.

Ayrıca bakınız:

  • httpd
  • apachectl
  • Başlatma

Giriş

Apache HTTP Sunucusunu durdurmak ve yeniden başlatmak için çalışan httpd süreçlerine bir sinyal göndermeniz gerekir. Sinyal göndermek için iki yol vardır. İlki, süreçlere doğrudan sinyal göndermek için unix kill komutunun kullanımıdır. Bu suretle, sisteminizde çalışmakta olan bir çok httpd sürecini uyarabilirsiniz ama süreç kimliği PidFile yönergesi ile belirtilen dosyada tutulan ana süreç dışında hiçbirine sinyal göndermemelisiniz. Başka bir deyişle, ana süreç haricinde hiçbir sürece sinyal göndermeye normal olarak ihtiyacınız olmaması gerekir. Ana sürece gönderebileceğiniz dört çeşit sinyal vardır: TERM, USR1, HUP ve WINCH. Bunlar yeri geldikçe açıklanacaktır.

Ana sürece kill ile sinyal göndermek için şöyle bir komut verebilirsiniz:

kill -TERM `cat /usr/local/apache2/logs/httpd.pid`

httpd süreçlerine sinyal göndermenin ikinci yolu -k komut satırı seçeneğini şu değerlerden biri ile kullanmaktır: stop, restart, graceful ve graceful-stop. Bunlar aşağıda açıklanacaktır. -k komut satırı seçeneği httpd’ye ait olsa da ana sürece bu sinyalleri göndermek için apachectl betiğini kullanmanızı öneririz. apachectl, komut satırı seçeneklerini httpd’ye aktaracaktır.

httpd’ye sinyal gönderdikten sonra olup biteni şu komutla izleyebilirsiniz:

tail -f /usr/local/apache2/logs/error_log

Bu örnekleri, kendi ServerRoot ve PidFile yönergelerinizdeki ayarlara uygun olarak değiştirdikten sonra kullanınız.

Hemen Durdur

Sinyal: TERM
apachectl -k stop

Ana sürece TERM veya stop sinyali göndererek tüm çocukların bir an önce öldürülmeye çalışılmasını sağlamış olursunuz. Tüm çocukların öldürülmesi bir kaç saniye sürebilir. Son olarak ana süreç çıkacaktır. Yanıtlanmakta olan istekler hemen sonlandırılacak ve artık isteklere yanıt verilmeyecektir.

Nazikçe Yeniden Başlat

Sinyal: USR1
apachectl -k graceful

Ana sürece USR1 veya graceful sinyalinin gönderilmesi, çocuklara ellerindeki mevcut işleri bitirdikten sonra (veya sundukları bir şey yoksa hemen) çıkmalarının önerilmesi demektir. Ana süreç kendi yapılandırma dosyalarını yeniden okur ve kendi günlük dosyalarını yeniden açar. Ana sürecin öldürdüğü her sürecin yerine yeni yapılandırma kuşağından bir süreç başlatır ve hemen yeni isteklere hizmet sunulmaya başlanır.

Bu kod MPM’lerin süreçleri denetleyen yönergelerine daima uyacak şekilde tasarlanmıştır. Bu suretle, istemcilere hizmet sunacak çocuk süreçler ve evreler, yeniden başlatma işleminde de uygun sayıda sağlanmış olur. Bununla birlikte, StartServers yönergesinde şöyle davranılır: İlk saniye içinde en azından StartServers sayıda yeni çocuk oluşturulmamışsa iş olmayan bir devreyi geçiştirecek kadarı oluşturulur. Ardından sunucunun mevcut yükünü karşılamak için gereken sayıda çocuk süreç oluşturulur. Bu suretle, kod her ikisi için de gereğini yerine getirmeye çalışmış olur.

mod_status kullanıcıları USR1 gönderildiği zaman sunucu istatistiklerinin sıfırlanmadığı konusunda uyarılacaktır. Kod, sunucunun yeni isteklere yanıt veremediği zamanı en aza indirmenin yanısıra ayar parametrelerinize de uymak üzere tasarlanmıştır (yeni istekler işletim sistemi tarafından kuyruğa alınacağından bir istek kaybı olayı yaşanmaz). Bunu sağlamak için, her iki kuşağın çocuklarının izini sürecek bir çetele tutulur.

mod_status modülü, nazikçe yeniden başlat komutunun verilmesinden önce başlamış ve sunulmaya devam eden isteklere bakan çocukları imlemek için ayrıca bir G (Graceful’un baş harfi) kullanır.

Günlük dosyası döndürme betiğine, yeniden başlatma öncesi günlüğe yazan tüm çocukların işini bitirdiğini USR1 kullanarak bildirmenin bir yolu yoktur. Önerimiz, eski günlük kaydı üzerinde bir işlem yapmaya başlamadan önce USR1 sinyali gönderilmesinin ardından belli bir süre beklenilmesi olacaktır. Örneğin, düşük band genişliğine sahip istemcilere hizmet sunan çoğu sürecin işinin 10 dakikadan önce bitmeyeceğini gözönüne alarak eski günlük üzerinde işlem yapmaya başlamak için 15 dakika beklenebilir.

Bir yeniden başlatma isteğinde, yapılandırma dosyalarında bir hata olmadığından emin olmak için önce bir sözdizimi denetimi yapılır. Eğer yapılandırma dosyalarınızda bir hata varsa bu sözdizimi hatasıyla ilgili bir hata iletisi alırsınız ve sunucu yeniden başlamayı reddeder. Bu yolla, bir hata sonucu sunucunun çökerek yeniden başlamaması nedeniyle işlevsiz bir sunucuyla başbaşa kalmanız önlenmiştir.

Ancak, bu hala sunucunuzun düzgünce yeniden başlatılmasını garanti etmeyecektir. Yapılandırma dosyalarınızı sözdizimi denetiminin yanında anlamlandırılması bakımından da sınamak için httpd’nin root olmayan bir kullanıcı tarafından çalıştırılmasını deneyebilirsiniz. Eğer yapılandırma dosyalarında bir hata yoksa soketleri ve günlük dosyalarını açmaya çalışırken root aidiyetinde çalışmadığından veya çalışmakta olan asıl sunucu bu portları zaten dinlediğinden başarısız olacaktır. Eğer başka bir sebeple başarısız olursa olası sebep bir yapılandırma dosyası hatasıdır ve asıl sunucuya ‘nazikçe yeniden başla’ komutunu vermeden önce bu hatayı düzeltmeniz gerekir.

Hemen Yeniden Başlat

Sinyal: HUP
apachectl -k restart

Ana sürece HUP veya restart sinyalinin gönderilmesi tüm çocukların TERM sinyali gönderilmiş gibi öldürülmesine sebep olur fakat ana sürecin çıkmasını sağlamaz. Ana süreç yapılandırma dosyalarını yeniden okur ve günlük kayıt dosyalarını yeniden açar. Bunların ardından isteklere yanıt verecek yeni kuşak çocukları oluşturmaya başlar.

mod_status kullanıcıları bir HUP sinyalı gönderildiğinde sunucu istatistiklerinin sıfırlandığı konusunda uyarılırlar.

‘Nazikçe yeniden başlat’ komutundaki gibi yeniden başlatma öncesi bir sözdizimi denetimi yapılır. Eğer yapılandırma dosyalarınızda sözdizimi hatası varsa yeniden başlatma işlemi gerçekleşmez ve sözdizimi hatalarıyla ilgili bildirim alırsınız.

Nazikçe Durdur

Sinyal: WINCH
apachectl -k graceful-stop

Ana sürecin WINCH veya graceful-stop sinyalini alması, çocuklara ellerindeki mevcut işleri bitirdikten sonra (veya sundukları bir şey yoksa hemen) çıkmalarının önerilmesine sebep olur. Ana süreç bunun hemen ardından PidFile dosyasını siler ve port dinlemeyi keser. Ana süreç çalışmaya ve isteklere yanıt vermekte olan çocuk süreçleri izlemeye devam eder. Tüm çocuklar işlerini bitirip çıktığında veya GracefulShutdownTimeout ile belirtilen zaman aşımı dolduğunda ana süreç de kendini sonlandırır. Eğer zaman aşımı devreye girmişse o an çalışmakta olan çocuk süreçlere TERM sinyali gönderilerek hemen çıkmaları sağlanır.

Bir TERM sinyali ile "graceful" durumundaki tüm çocuklar ve ana süreç hemen sonlandırılacaktır. Bununla birlikte, PidFile dosyası da silineceğinden, artık apachectl veya httpd’yi bu sinyali göndermek için kullanamayacaksınız.

graceful-stop sinyali, aynı anda, aynı yapılandırma ile çok sayıda httpd kopyasının çalıştırılabilmesine imkan verir. Bu, Apache nazikçe yükseltileceği zaman güçlü bir özellik haline gelmekteyse de, bazı yapılandırmalarda yarış koşullarının oluşmasına ve kısır çekişmelere (deadlock) sebep olabilir.

Sunucunun süreç kimliğini içeren kilit dosyaları (Mutex) ve Unix soket dosyaları (ScriptSock) gibi dosyaların disk üzerindeki mevcudiyetlerinin sorunsuz olarak devam ettiğinden emin olunmaya çalışılmalıdır. Ayrıca, bir yapılandırma yönergesi, üçüncü parti bir modül veya kalıcı CGI uygulamalarına ait disk kilit veya durum dosyaları olabilir; httpd’nin birden fazla kopyasının çalışması nedeniyle bu dosyaların da üzerine yazılmadığından emin olunmaya çalışılmalıdır.

rotatelogs tarzı borulu günlükleme kullanımı gibi durumlarda yarış koşullarının oluşması olasılığına karşı uyanık olunmalıdır. Aynı günlük kayıt dosyalarını aynı anda döndürmeye çalışan birden fazla rotatelogs kopyasının çalıştırılması halinde bunların her biri diğerlerinin günlük kayıt dosyalarının kaybına sebep olabilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Yapılandırma Dosyaları - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Yapılandırma Dosyaları

Bu belgede Apache HTTP Sunucusunu yapılandırmakta kullanılan dosyalar açıklanmıştır.

Ana Yapılandırma Dosyaları

İlgili Modüller İlgili Yönergeler
  • mod_mime
  • <IfDefine>
  • Include
  • TypesConfig

Apache HTTP Sunucusu düz metin yapılandırma dosyalarına yönergeler yerleştirilerek yapılandırılır. Ana yapılandırma dosyasının ismi normalde httpd.conf’tur. Bu dosyanın yeri derleme sırasında belirlenir, ancak çalıştırma sırasında -f komut satırı seçeneği ile başka bir yer belirtilebilir. Ayrıca, Include yönergesi kullanılarak başka yapılandırma dosyaları da eklenebilir ve bu dosyaların isimleri belirtilirken dosya ismi şablonları kullanılabilir. Bu dosyaların içine de ana yapılandırma dosyasında olduğu gibi her türlü yönerge yerleştirilebilir. Ana yapılandırma dosyalarındaki değişiklikler httpd tarafından sadece başlatma veya yeniden başlatma sırasında etkin kılınır.

Sunucu ayrıca MIME belge türlerini içeren bir dosya daha okur; dosya ismi öntanımlı olarak mime.types olup TypesConfig yönergesi ile başka bir dosya belirtilebilir.

Yapılandırma Dosyalarının Sözdizimi

httpd yapılandırma dosyalarının her satırında sadece bir yönerge bulunur ve bir yönergenin birden fazla satıra yayılması daha iyi olacaksa satır katlanabilir; devamı bir alt satırda olan her satırın son karakteri “\” (tersbölü) olmalı, satırsonu karakteri ile bu tersbölü karakteri arasında başka karakter bulunmamalıdır.

Yönergelerdeki değiştirgeler boşluklarla ayrılır. Eğer bir değiştirge kendi içinde boşluklar içeriyorsa tırnak içine alınır.

Yapılandırma dosyalarındaki yönergelerin isimleri harf büyüklüğüne duyarlı olduğu halde argümanları genellikle harf büyüklüğüne duyarlı değildir. Diyez (“#”) karakteri ile başlayan satırlar açıklama olarak ele alınır ve yok sayılırlar. Yapılandırma yönergesi içeren satırlara açıklama yerleştirilemez. Yönerge isminden önce yer alan boşluklar yoksayılır; bu özellik, okunabilirliği sağlamak için yönergelerin girintilenebilmesi olanağını verir. Ayrıca, boş satırlar da yoksayılır.

Define ile veya kabuğun ortam değişkenleri ile tanımlanmış değişkenlerin değerleri, yapılandırma dosyasının satırlarında ${VAR} sözdizimi ile kullanılabilir. "VAR" geçerli bir değişkenin adı olduğu takdirde, bu değişkenin değeri yapılandırma dosyasının bu noktasında yerine konacak ve orada zaten değişken yerine değeri varmış gibi işlem kaldığı yerden devam edecektir. Define ile tanımlanmış değişkenler kabuğun ortam değişkenlerinden önceliklidir. "VAR" diye bir değişken yoksa ${VAR} içindeki karakterler değişmeden kalır ve günlüğe bir uyarı çıktılanır. RewriteMap sözdizimi ile olası bir karışıklığı önlemek için, değişken isimleri iki nokta imini (":") içeremez.

Kabuğun ortam değişkenlerinin, sadece, sunucu başlatılmadan önce tanımlanmış değerleri kullanılabilir. Yapılandırma dosyasının kendisinde tanımlanmış ortam değişkenleri (örneğin, SetEnv ile), yapılandırma dosyasındaki işlemlerde çok daha sonra yer alır.

Yapılandırma dosyasındaki bir satırın uzunluğu, değişken ikamesi yapıldıkta, devam satırları eklenditen sonra en fazla 16MiB olabilir. .htaccess dosyalarında azami uzunluk 8190 karakterdir.

Sunucuyu başlatmadan önce apachectl configtest ile veya -t komut satırı seçeneği ile yapılandırma dosyalarınızı sözdizimi hatalarına karşı sınayabilirsiniz.

Eşleşmeyen <IfDefine> ve <IfModule> bölümleri kaldırılmış, tüm açıklamalar, çözümlenmiş ortam değişkenleri ve içerilmiş tüm dosyalar dahil yapılandırmanın bir dökümünü almak için mod_info'nun -DDUMP_CONFIG seçeneğini kullanabilirsiniz. Ancak, çıktı yinelenen yönergeler için katıştırılan veya geçersiz kılınanları yansıtmayacaktır.

Modüller

İlgili Modüller İlgili Yönergeler
  • mod_so
  • <IfModule>
  • LoadModule

httpd modüler yapıda bir sunucudur. Bu, çekirdek sunucunun sadece en temel işlevselliği içermesi demektir. Ek özellikler, httpd’ye modüller halinde yüklenebilir. Öntanımlı olarak, derleme sırasında sunucunun temel bir modül kümesi içermesi sağlanır. Eğer sunucu devingen yüklenen modülleri kullanmak üzere yapılandırılarak derlenirse modüller ayrı olarak derlenip gerektiği zaman LoadModule yönergesi kullanılarak yüklenebilir. Aksi takdirde, ek modülleri yükleyebilmek veya kaldırabilmek için httpd’nin yeniden derlenmesi gerekir. Yapılandırma yönergeleri belli bir modülün varlığına dayalı olarak bir <IfModule> bloku içine alınmak suretiyle sunucuya koşullu olarak eklenebilir. Ancak, <IfModule> yönergeleri gerekli değildir, önemli bir modülün yokluğu gibi durumlarda maskelenebilir.

Sunucunun içinde derlenmiş modüllerin listesini görmek için -l komut satırı seçeneğini kullanabilirsiniz. Ayrıca, -M komut satırı seçeneği ile hangi modüllerin devingen olarak yüklendiğini görebilirsiniz.

Yönergelerin Etki Alanı

İlgili Modüller İlgili Yönergeler
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <Location>
  • <LocationMatch>
  • <VirtualHost>

Ana yapılandırma dosyasına yerleştirilen yönergeler sunucunun tamamına uygulanır. Yapılandırmanızı sunucunun belli bir parçası için değiştirmek isterseniz yönergelerinizi <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location> ve <LocationMatch> bölümleri içine yerleştirerek etki alanlarını değiştirebilirsiniz. Bu bölümler yönergelerin etkilediği alanları dosya sistemininin belli yerleri veya belli URL’lerle sınırlar. Yerine göre daha hassas ayarlamalar yapmak için bu bölgeler iç içe de kullanılabilir.

httpd, çok sayıda farklı siteyi aynı anda sunabilecek yetenektedir. Buna Sanal Konaklık adı verilir. Yönergelerin etki alanları ayrıca <VirtualHost> bölümleri içine konarak da değiştirilebilir. Böylece belli bir siteye gelen isteklere farklı bir uygulama yapılabilir.

Yönergelerin çoğu bu bölümlere yerleştirilebilirse de bazı yönergelerin bazı bağlamlarda bir etkisi olmaz. Örneğin, süreç oluşturmayı denetleyen yönergeler sadece ana sunucu bağlamına yerleştirilebilir. Hangi yönergenin hangi bağlama yerleştirilebileceğini bulmak için yönergenin bağlamına bakınız. Bu konuda daha ayrıntılı bilgi edinmek için: Directory, Location ve Files Bölümleri Nasıl Çalışır.

.htaccess Dosyaları

İlgili Modüller İlgili Yönergeler
  • AccessFileName
  • AllowOverride

httpd yapılandırma sorumluluğunu dağıtmak için site ağaçları içine özel dosyalar yerleştirilmesine izin verir. Bu özel dosyalar normalde .htaccess dosyaları olmakla birlikte AccessFileName yönergesi kullanılarak rasgele bir isim belirtilebilir. .htaccess dosyalarına yerleştirilen yönergeler sadece dosyanın bulunduğu dizine ve alt dizinlerine uygulanır. .htaccess dosyalarında da ana yapılandırma dosyalarında geçerli sözdizimi kullanılır. .htaccess dosyaları her istek gelişinde yeniden okunduğundan bu dosyalarda yapılan değişiklikler hemen etkisini gösterir.

.htaccess dosyalarına hangi yönergelerin yerleştirilebileceğini bulmak için yönerge bağlamına bakınız. Sunucunun yöneticisi .htaccess dosyalarına hangi yönergelerin yerleştirilebileceğini ana yapılandırma dosyalarında AllowOverride yönergesini kullanarak belirleyebilir.

.htaccess dosyaları hakkında daha ayrıntılı bilgi edinmek için .htaccess öğreticisine bakabilirsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Yapılandırma Bölümleri - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Yapılandırma Bölümleri

Yapılandırma dosyalarındaki yönergeler sunucunun tamamına uygulanacağı gibi sadece belli dizinler, dosyalar, konaklar veya URL’lere uygulanmakla sınırlanabilir. Bu belgede, yapılandırma bölümü taşıyıcılarınının veya .htaccess dosyalarının, yapılandırma dosyalarındaki diğer yönergelerin etki alanlarını değiştirtirmek için nasıl kullanılacağı açıklanmıştır.

Yapılandırma Bölümü Taşıyıcılarının Türleri

İlgili Modüller İlgili Yönergeler
  • core
  • mod_version
  • mod_proxy
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <If>
  • <IfDefine>
  • <IfModule>
  • <IfVersion>
  • <Location>
  • <LocationMatch>
  • <Proxy>
  • <ProxyMatch>
  • <VirtualHost>

İki temel taşıyıcı türü vardır. Taşıyıcıların çoğu her istek için değerlendirmeye alınır. Taşıyıcılardaki yönergeler ise sadece bu taşıyıcılarla eşleşen istekler için uygulanır. Diğer yandan, <IfDefine>, <IfModule> ve <IfVersion> taşıyıcıları sadece sunucu başlatılırken veya yeniden başlatılırken değerlendirmeye alınır. Başlatma sırasında gerektirdikleri koşullar sağlanıyorsa içerdikleri yönergeler tüm isteklere uygulanır. Aksi takdirde, içerdikleri yönergeler yok sayılır.

<IfDefine> yönergesi sadece httpd komut satırında uygun parametreler tanımlanmışsa uygulanabilecek yönergeleri içerir. Örneğin, aşağıdaki yapılandırma ile tüm isteklerin diğer siteye yönlendirilebilmesi sadece sunucu httpd -DClosedForNow komut satırı ile başlatıldığı takdirde mümkün olur:

<IfDefine ClosedForNow>
  Redirect "/" "http://otherserver.example.com/"
</IfDefine>

<IfModule> yönergesi sadece belli bir modülün sunucuda kullanılabilir durumda olması halinde uygulanabilecek yönergeleri içerir. Modülün ya sunucuyla birlikte durağan olarak derlenmiş olması ya da devingen olarak derlenmiş ve yapılandırma dosyasında yönergeden önce o modüle ilişkin bir LoadModule satırının bulunması gerekir. Bu yönergeyi sadece belli bir modülün varlığının veya yokluğunun yapılandırma dosyanızın çalışmasını etkilememesini istediğiniz durumlarda kullanmalısınız. Eksik modüllerle ilgili hata iletilerini engellediğinden, taşıyıcı içine, her zaman çalışması istenen yönergeler konulmamalıdır.

Aşağıdaki örnekte, MimeMagicFile yönergesi sadece mod_mime_magic modülü mevcutsa uygulanacaktır.

<IfModule mod_mime_magic.c>
  MimeMagicFile "conf/magic"
</IfModule>

<IfVersion> yönergesi sunucunun belli bir sürümünün çalıştırılması halinde uygulanabilecek yönergeleri içerebilmesi dışında <IfDefine> ve <IfModule> yönergeleri gibidir. mod_version modülü farklı httpd sürümleri ve farklı yapılandırmalarla büyük ağlarda çalışmayı mümkün kılmak veya sürüm denemeleri yapabilmek amacıyla tasarlanmıştır.

<IfVersion >= 2.4>
  # burası sadece 2.4.0 veya daha üstü sürümlerde
  # iş görür.
</IfVersion>

<IfDefine>, <IfModule> ve <IfVersion> yönergelerinin önüne "!" konularak olumsuz koşullar için uygulanabilir. Ayrıca, bu bölümler daha karmaşık sınırlamalar elde etmek amacıyla bir diğerinin içinde kullanılabilirler.

Dosya Sistemi, Site Alanı ve Mantıksal İfadeler

En sık kullanılan yapılandırma bölümü taşıyıcıları dosya sistemindeki veya site alanındaki belli yerlerin yapılandırmalarını değiştirmekte kullanılanlardır. Öncelikle, bu ikisi arasındaki farkları bilmek önemlidir. Dosya sistemi disklerinizin işletim sistemi tarafından size gösterilen halidir. Örneğin, öntanımlı kurulumda Apache httpd, Unix sistemlerinde /usr/local/apache2 altındayken Windows sistemlerinde "c:/Program Files/Apache Group/Apache2" altındadır. (Bilgi: Windows için bile, Apache httpd yapılandırma dosyalarında dosya yolu belirtilirken tersbölü değil normal bölü karakterleri kullanılır.) Site alanı ise sunucu tarafından istemciye sunulan dizin ağacıdır. Yani, site alanı içindeki /dir/ dizini, Apache httpd’nin Unix üzerinde dosya sistemine öntanımlı olarak kurulduğu yer göz önüne alınarak, dosya sistemindeki /usr/local/apache2/htdocs/dir/ dizinine karşılıktır. Site sayfaları veritabanlarından veya başka yerlerden devingen olarak üretilebildiğinden site alanlarının doğrudan dosya sistemine eşlenmesi gerekli değildir.

Dosya Sistemi Taşıyıcıları

<Directory> ve <Files> taşıyıcıları, düzenli ifade karşılıkları ile beraber, yönergeleri dosya sisteminin parçalarına uygularlar. Bir <Directory> bölümü içindeki yönergeler belli bir dosya sistemi dizinine ve onun alt dizinlerine uygulanır. Aynı etki .htaccess dosyaları kullanılarak da sağlanabilir. Örneğin aşağıdaki yapılandırmada, /var/web/dir1 dizini ve alt dizinlerinde dizin içeriğinin listelenmesi etkin kılınmaktadır.

<Directory "/var/web/dir1">
  Options +Indexes
</Directory>

Bir <Files> bölümü içindeki yönergeler, hangi dizinde bulunduğuna bakılmaksızın ismi belirtilen dosyalara uygulanır. Örneğin, aşağıdaki yapılandırma yönergeleri yapılandırma dosyasının ana bölümüne yerleştirildiği takdirde gizli.html isimli dosyalara nerede bulunursa bulunsun erişime izin vermeyecektir.

<Files "gizli.html">
  Require all denied
</Files>

Dosya sisteminin belli bir yerindeki belli dosyalarla ilgili yaptırımlar için <Files> ve <Directory> bölümleri birlikte kullanılabilir. Örneğin, aşağıdaki yapılandırma /var/web/dir1/gizli.html, /var/web/dir1/subdir2/gizli.html, /var/web/dir1/subdir3/gizli.html ve /var/web/dir1/ altında bulunabilecek diğer tüm gizli.html dosyalarına erişimi yasaklar.

<Directory "/var/web/dir1">

  <Files "gizli.html">

    Require all denied
  </Files>

</Directory>

Site Alanı Taşıyıcıları

<Location> yönergesi ve yönergenin düzenli ifade karşılığı site alanındaki içerik için yapılandırmayı değiştirir. Örneğin aşağıdaki yapılandırma, /gizli ile başlayan URL yollarına erişimi engeller. Özellikle, http://siteniz.mesela.dom/gizli, http://siteniz.mesela.dom/gizli123 ve http://siteniz.mesela.dom/gizli/dir/dosya.html istekleri yanında /gizli ile başlayan diğer isteklere de uygulanır.

<LocationMatch "^/gizli">
    Require all denied
</LocationMatch>

Dosya sistemi ile etkileşime girmeyen herşey için <Location> yönergesi gerekir. Aşağıdaki örnekte, belli bir URL’nin mod_status modülü tarafından sağlanan bir dahili Apache eylemcisine nasıl eşlenebileceği gösterilmiştir. Bu örnek için dosya sisteminde server-status adında bir dosya veya dizin bulunması gerekli değildir.

<Location "/server-status">
    SetHandler server-status
</Location>

Site Alanında Çakışma

Belli bölümler ve yönergeler değerlendirilirken çakışan iki URL bir URL olarak dikkate alınır. <Location> yönergesi için bu şöyle olurdu:

<Location "/foo">
</Location>
<Location "/foo/bar">
</Location>

Diğer yandan <Takma adlar> tam tersi eşlenir:

Alias "/foo/bar" "/srv/www/uncommon/bar"
Alias "/foo" "/srv/www/common/foo"

Aynısı ProxyPass yönergeleri için de geçerlidir:

ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On

Dosya Adı Şablonları ve Düzenli İfadeler

<Directory>, <Files> ve <Location> yönergelerinde, Standart C kütüphanesindeki fnmatch işlevindeki gibi kabuk tarzı dosya ismi kalıpları kullanılabilir. "*" karakteri herhangi bir karakter dizisi ile eşleşirken "?" karakteri tek tek karakterlerle ve "[seq]" kalıbı ise seq içindeki her karakterle eşleşir. "/" karakteri her hangi bir kalıp karakteri ile eşleşmez; açıkça belirtilmesi gerekir.

Daha esnek bir eşleşmenin gerekli olduğu durumlar için her taşıyıcının bir düzenli ifade karşılığı vardır. <DirectoryMatch>, <FilesMatch> ve <LocationMatch> yönergelerinde gerekli eşleşmeleri seçmek için perl uyumlu düzenli ifadelerin kullanımına izin verilir. Ayrıca, yönergelerin uygulanışının düzenli ifade bölümleri kullanılarak nasıl değiştirileceğini öğrenmek için, aşağıda, yapılandırmanın katıştırılmasıyla ilgili bölüme de bakınız.

Tüm kullanıcı dizinlerine ilişkin yapılandırmayı değiştirmek için dosya ismi kalıpları şöyle kullanılabilirdi:

<Directory "/home/*/public_html">
    Options Indexes
</Directory>

Düzenli ifade bölümleri kullanarak çeşitli türlerdeki resim dosyalarına erişimi bir defada yasaklayabiliriz:

<FilesMatch "\.(?i:gif|jpe?g|png)$">
    Require all denied
</FilesMatch>

İsimli gruplar ve geriye başvurular içeren düzenli ifadeler ortama eklenirken ilgili isimler büyük harfli yapılır. Böylece, URL'lere ve dosya yolları elemanlarına ifadelerin içinden ve mod_rewrite gibi modüllerden başvurmak mümkün olur.

<DirectoryMatch "^/var/www/combined/(?<SITENAME>[^/]+)">
    require ldap-group "cn=%{env:MATCH_SITENAME},ou=combined,o=Example"
</DirectoryMatch>

Mantıksal İfadeler

<If> yönergesi bir mantıksal ifade olarak belirtilebilen bir kurala bağlı olarak yapılandırmayı değiştirebilir. Örneğin, aşağıdaki yapılandırmada, HTTP Referer başlığı "http://www.example.com/" ile başlamıyorsa erişimi yasaklar.

<If "!(%{HTTP_REFERER} -strmatch 'http://www.example.com/*')">
    Require all denied
</If>

Ne, Ne Zaman Kullanılır?

Dosya sistemi taşıyıcıları ile site alanı taşıyıcıları arasında seçim yapmak aslında oldukça kolaydır. Dosya sisteminde bulunan nesnelere uygulanacak yönergeler için daima <Directory> veya <Files> kullanılır. Dosya sisteminde bulunmayan nesnelere (bir sayfanın bir veritabanı tarafından üretilmesi gibi) uygulanacak yönergeler için ise <Location> kullanılır.

Dosya sistemindeki nesnelere erişimi kısıtlarken asla <Location> kullanmamak önemlidir. Bunun sebebi farklı site alanı konumlarının (URL’ler) aynı dosya sistemi konumuna eşlenebilmesi dolayısıyla kısıtlamalarınızın etrafından dolaşılabilmesine izin vermesidir. Örneğin, aşağıdaki yapılandırmayı ele alalım:

<Location "/dir/">
    Require all denied
</Location>

http://siteniz.mesela.dom/dir/ için bir istek yapılmışsa bu doğru çalışacaktır. Fakat dosya sistemi harf büyüklüğüne duyarsızsa ne olacak? Kısıtlamanız, istek http://siteniz.mesela.dom/DIR/ şeklinde yapılarak kolayca geçersiz kılınabilir. Halbuki <Directory> yönergesi isteğin nasıl yapıldığına bakılmaksızın bu konumdan sunulan her türlü içeriğe uygulanacaktı. (Dosya sistemi bağlarıyla bu da aşılabilir. Sembolik bağlar kullanılarak aynı dizin dosya sisteminin bir çok yerine yerleştirilebilir. <Directory> yönergesi dosya yolunu sıfırlamaksızın sembolik bağları izleyecektir. Bu bakımdan, en yüksek seviyede güvenlik için uygun Options yönergesi ile sembolik bağların izlenmesi devredışı bırakılabilir.)

Belki de siz sırf harf büyüklüğüne duyarlı bir dosya sistemi kullanıyorsunuz diye böyle uygulamalara ihtiyacınız olmadığını düşünüyor olabilirsiniz, fakat aynı site alanını çok sayıda dosya sistemi konumuna eşleyecek daha bir sürü yol bulunduğunu unutmayınız. Bu bakımdan dosya sisteminde yapacağınız kısıtlamalarda daima dosya sistemi taşıyıcılarını kullanmalısınız. Bununla birlikte bu kuralın da bir istisnası vardır. Yapılandırma kısıtlamalarının bir <Location "/"> bölümü içine koyulması, bu bölüme konan yönergelerin etki alanının belli bir URL ile sınırlı olmaması nedeniyle mükemmelen güvenlidir.

Bölüm iç içeliği

Bazı bölüm türleri başka bölüm türlerinin içinde olabilir. Bir yandan, <Files> bölümü <Directory> bölümünün içinde bulunabilirken diğer yandan bir <If> bölümü <Directory>, <Location> ve <Files> bölümlerinde bulunabilir. Bu bölümlerin düzenli ifadeli türevleri de benzer tarzda davranır.

İç içe bölümler, aynı türdeki iç içe olmayan bölümlerin sonrasına yerleştirilir.

Sanal Konaklar

<VirtualHost> taşıyıcısının içinde belli bir konağa uygulanan yönergeler bulunur. Aynı makinede çok sayıda konağı farklı yapılandırmalarla sunuyorsanız bu taşıyıcı çok işinize yarar. Daha fazla bilgi için Sanal Konak Belgeleri bölümüne bakınız.

Vekil

<Proxy> ve <ProxyMatch> taşıyıcıları, sadece belli bir URL ile eşleşen mod_proxy vekil sunucusu üzerinden erişilen sitelere uygulanan yapılandırma yönergelerini bulundururlar. Örneğin aşağıdaki yapılandırma example.com sitesine erişim için vekil sunucunun sadece ağdaki bazı kullanıcılar tarafından kullanılabilmesini sağlayacaktır.

<Proxy "http://www.example.com/*">
    Require host bizimki.example.com
</Proxy>

Hangi Yönergelere İzin Veriliyor?

Hangi yönergelere hangi yapılandırma bölümlerinde izin verildiğini öğrenmek için yönerge bağlamına bakınız. <Directory> bölümlerinde izin verilen herşeye sözdizimsel olarak ayrıca <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch>, <Proxy> ve <ProxyMatch> bölümlerinde de izin verilir. Yine de bazı istisnai durumlar mevcuttur:

  • AllowOverride yönergesi sadece <Directory> bölümlerinde çalışır.
  • Options yönergesinin FollowSymLinks ve SymLinksIfOwnerMatch seçenekleri sadece <Directory> bölümlerinde veya .htaccess dosyalarında çalışır.
  • Options yönergesi <Files> ve <FilesMatch> bölümlerinde kullanılamaz.

Bölümler Nasıl Katıştırılır?

Yapılandırma bölümleri belli bir sıra ile uygulanır. Yapılandırma yönergelerinin yorumlanışı üzerinde önemli etkilere sahip olabilmesi nedeniyle neyin ne zaman çalıştığını anlamak çok önemlidir.

Yapılandırma bölümlerinin katıştırılma sırası şöyledir:

  1. <Directory> (düzenli ifadeler hariç) ve .htaccess aynı anda işleme sokulur (.htaccess ile eğer izin verilmişse <Directory> içindeki bazı yönergeler geçersiz kılınabileceği için).
  2. <DirectoryMatch> (ve <Directory "~">).
  3. <Files> ve <FilesMatch> aynı anda işleme sokulur.
  4. <Location> ve <LocationMatch> aynı anda işleme sokulur.
  5. <If>

<Directory> bölümündekiler hariç, her grup, yapılandırma dosyasında bulundukları sıraya göre işleme sokulurlar. Yukarıda 1. grup olan <Directory> bölümü en kısa dizin elemanından en uzun dizin elemanına doğru işleme sokulur. Yani, örneğin, <Directory "/var/web/dir"> bölümü <Directory "/var/web/dir/subdir"> bölümünden önce işleme sokulacaktır. Eğer aynı uzunlukta çok sayıda dizin varsa <Directory> bölümleri yapılandırma dosyasında bulundukları sıraya göre işleme sokulurlar. Include yönergeleri ile yapılandırmaya dahil edilen dosyaların içerikleri Include yönergesinin bulunduğu yere konulduktan sonra işleme sokulurlar.

<VirtualHost> bölümlerinin içindeki bölümler, sanal konak tanımı dışındaki karşılıklarından sonra uygulanırlar.

İstek mod_proxy tarafından sunulduğu takdirde, <Proxy> taşıyıcısı işlem sırasında <Directory> taşıyıcısının yerini alır.

Bazı Teknik Bilgiler

Aslında, isim dönüşüm aşamasından (Aliases ve DocumentRoots, URL’leri dosya isimlerine eşlemek için kullanılırken) hemen önce uygulanan bir <Location>/<LocationMatch> dizisi vardır. Bu dizinin sonuçları isim dönüşüm aşaması tamamlandıktan sonra tamamen elden çıkarılır.

Modüllerle yapılandırma bölümleri arasındaki ilişki

Yapılandırma bölümlerini okurken örneğin mod_rewrite gibi belli modüllerin yönergelerinin bu bölümlere nasıl katılacağı ve ne zaman nasıl işleneceği gibi sorular sıkça aklımızdan geçer. Bunun belli bir yanıtı yoktur ve biraz temel bilgi gerektirir. Her httpd modülü yapılandırmasını kendi yönetir ve httpd.conf içindeki yönergelerinin her biri belli bir bağlamdaki bir yapılandırmayı belirtir. httpd bir komutu okunduğu sırada çalıştırmaz.

Çalışma anında, httpd çekirdeği geçerli isteğe hangilerinin uygulanacağını belirlemek için yukarıda açıklanan sırada tanımlı yapılandırma bölümlerini tekrar tekrar okur. Eşleşen ilk bölümün bu istek için geçerli yapılandırmayı içerdiği varsayılır. Eğer alt bölümlerden biri de eşleşmişse bu bölümlerde yönergeleri bulunan her modüle yapılandırmasını iki bölüm arasında katıştırma şansı verilir. Sonuç üçüncü bir yapılandırma olup işlem bütün yapılandırma bölümleri değerlendirilene kadar sürer.

Yukarıdaki adımların ardından HTTP isteğiyle ilgili "asıl" işlem başlar: her modül ondan istenen görevleri gerçekleştirme şansına sahip olur. Nasıl davranacaklarını belirlemek için kendilerinin katıştırılmış son yapılandırmalarını http çekirdeğinden alabilirler.

Sürecin tamamı bir örnekle görselleştirilebilir. Aşağıdaki örnekte belli bir HTTP başlığını ayarlamak için mod_headers modülünün Header yönergesi kullanılmıştır. /example/index.html isteği için httpd CustomHeaderName başlığına hangi değeri atayacaktır?

<Directory "/">
    Header set CustomHeaderName bir
    <FilesMatch ".*">
        Header set CustomHeaderName yedi
    </FilesMatch>
</Directory>

<Directory "/example">
    Header set CustomHeaderName iki
</Directory>
  • Directory "/" eşleşir ve ilk yapılandırma olarak CustomHeaderName başlığı bir değeriyle oluşturulur.
  • Directory "/example" eşleşir ve mod_headers modülünün koduna göre bir katıştırma durumundan yeni değer eskiyi geçersiz kılacağından yeni bir yapılandırma ile CustomHeaderName başlığının değeri iki yapılır.
  • FilesMatch ".*" eşleşir ve başka bir katıştırma fırsatı doğar: CustomHeaderName başlığının değeri yedi yapılır.
  • Neticede HHP isteğinin sonraki adımlarında mod_headers çağrılıp yedi değeri atanmış CustomHeaderName başlığını işleme sokması istenecektir. mod_headers normalde işini yapmak için bu yapılandırmayı kullanacaktır. Fakat bundan, bir yönergenin gerekli olmaması veya kullanımdan kaldırılması ve benzeri nedenlerle yapılandırmada iptal edilmesi gibi daha karmaşık bir eylemi bir modülün gerçekleştiremeyeceği anlamı çıkarılmamalıdır.

Directory ile aynı katıştırma sırasından dolayı bu durum .htaccess için de geçerlidir. Burada anlaşılması gereken husus, Directory ve FilesMatch gibi yapılandırma bölümlerinin Header veya RewriteRule gibi modüle özgü yönergelerle karşılaştırılmamasıdır, çünkü bunlar farklı seviyelerde işlem görür.

Bazı Örnekler

Aşağıdaki yapay örnekte katıştırma sırası gösterilmiştir. Hepsinin aynı isteğe uygulandığı varsayımıyla, bu örnekteki yönergeler A > B > C > D > E sırasıyla uygulanacaktır.

<Location "/">
    E
</Location>

<Files "f.html">
    D
</Files>

<VirtualHost *>
<Directory "/a/b">
    B
</Directory>
</VirtualHost>

<DirectoryMatch "^.*b$">
    C
</DirectoryMatch>

<Directory "/a/b">
    A
</Directory>

Daha somut bir örnek olarak aşağıdakini ele alalım. <Directory> bölümlerindeki erişim sınırlamaları ne olursa olsun <Location> bölümü son olarak değerlendirmeye alınacak ve sunucuya sınırsız erişim verecektir. Başka bir deyişle, katıştırma sırası önemlidir, bu nedenle dikkatli olmalısınız!

<Location "/">
    Require all granted
</Location>

# Alooo!  Bu <Directory> bölümünün hiçbir hükmü yok.
<Directory "/">
    <RequireAll>
        Require all granted
        Require not host kkadam.example.com
    </RequireAll>
</Directory>

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Önbellek Kullanım Kılavuzu - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Önbellek Kullanım Kılavuzu

Bu belge mod_cache, mod_cache_disk, mod_file_cache modülleri ve htcacheclean için bir başvuru kılavuzu niteliğindedir. HTTP sunucusu ve vekil olarak çalışmada işlemleri hızlandırmak için bilinen sorunlar ve yanlış yapılandırmalardan kaçınarak Apache HTTPD sunucusunun önbellekleme özelliklerinin nasıl kullanılacağı açıklanmıştır.

Giriş

Apache HTTP sunucusu, sunucunun başarımını çeşitli yollarla arttırmak üzere tasarlanmış bir dizi önbellekleme özelliğine sahiptir.

Üç durumlu RFC2616 HTTP önbelleklemesi
mod_cache ve destek modülü mod_cache_disk akılcı ve HTTP'ye uygun önbellekleme sağlar. İçeriğin kendisi önbellekte saklanır ve mod_cache, RFC2616'nın 13. bölümünde açıklandığı gibi, içeriğin önbelleklenebilirliğini denetleyen çeşitli HTTP başlıklarının ve seçeneklerinin tümünü onurlandırmayı hedefler. Devingen yerel içerik veya vekalet edilen içerik ile ilgilendiğiniz durumda veya muhtemel bir yavaş disk üzerinde yerel dosyalara erişimi hızlandırmak ihtiyacında olduğunuz durumda mod_cache hem basit hem de karmaşık önbellekleme yapılandırmalarını hedefler.
İki durumlu anahtar/değer paylaşımlı nesne önbellekleme
Paylaşımlı nesne önbellek API'si (socache) ve destek modülleri sunucu taraflı bir anahtar/değer paylaşımlı nesne önbelleklemesi sağlar. Bu modüller SSL oturumları ve kimlik doğrulama bilgileri gibi düşük seviyeli verileri önbelleklemek için tasarlanmıştır. Destek modülleri verinin sunucu tarafı bir paylaşımlı bellekte veya veri merkezi tarafı memcache veya distcache gibi bir önbellekte saklanmasını mümkün kılar.
Uzmanlaşmış dosya önbellekleme
mod_file_cache dosyaların sunucunun başlatılması sırasında belleğe yüklenmesi ile ilgilenir. Böylece dosyalara erişim zamanını kısaltabilir, sıkça erişilen dosyaların dosya tanıtıcılarını kaydedebilir, her istekte diske gitme ihtiyacını ortadan kaldırır.

Bu belgeden azami yararı sağlayabilmek için temel bir HTTP bilginizin olması ve URL’lerin Dosya Sistemine Eşlenmesi ile İçerik Uzlaşımı belgelerini okumuş olmanız gerekir.

Üç durumlu RFC2616 HTTP önbelleklemesi

İlgili Modüller İlgili Yönergeler
  • mod_cache
  • mod_cache_disk
  • CacheEnable
  • CacheDisable
  • UseCanonicalName
  • CacheNegotiatedDocs

HTTP protokolü RFC2616'nın 13. bölümünde açıklanan satıriçi önbellekleme mekanizması için yerleşik bir destek içerir ve bunun getirilerinden yararlanmak için mod_cache modülü kullanılabilir.

İçeriğin taze olmadığı durumda içeriğin kaybolmasına sebep olan basit iki durumlu anahtar/değer önbelleklemesinin tersine, HTTP önbelleği eskimiş içeriği tutan ve bu eski içeriğin değişip değişmediğini özgün sunucuya soran ve duruma göre onu tekrar taze duruma getiren bir mekanizma içerir.

HTTP önbelleğinde bulunan bir girdi şu üç durumdan birinde olabilir:

Taze
İçerik yeteri kadar yeni (tazelik ömründen daha genç) ise taze sayılır. Bir HTTP önbelleği böyle bir içeriği özgün sunucuya birşey sormadan sunabilir.
Bayat

İçerik çok eski (tazelik ömründen daha yaşlı) ise bayat sayılır. Bir HTTP önbelleği böyle bir içeriği istemciye sunmadan önce özgün sunucuya bağlanıp bayat içeriğin hala yeterince taze olup olmadığına bakmalıdır. Özgün sunucu, içerik geçersizse yenisini gönderecektir, aksi takdirde, (ideal olanı budur) içeriğin hala geçerli olduğunu belirten bir kod ile yanıt verecektir. İçerik tekrar taze hale gelince süreç kaldığı yerden devam eder.

HTTP protokolü belli koşullar altında önbelleğin bayat içeriği sunmasına izin vermez. Örneğin, bir içeriği özgün sunucuda tazeleme çabasının bir 5xx hatasıyla başarısız olması veya başka bir tazeleme isteğinin henüz sonuçlanmamış olması bu çeşit koşullardandır. Bu durumlarda yanıta bir Warning başlığı eklenir.

Yok
Önbellekte yer kalmazsa yer açmak için içeriğin silinmesi seçenek dahilindedir. İçerik taze olsun olmasın her zaman silinebilir. Önlem olarak htcacheclean elle veya bir artalan süreci olarak çalıştırılabilir. Böylece önbelleğin boyutunun belirtilen boyutta veya belirtilen dosya düğümü sayısında kalması sağlanabilir. Araç içeriği silerken bayat içeriğe öncelik verir.

HTTP önbelleklemesinin çalışması ile ilgili bütün ayrıntılar RFC2616'nın 13. bölümünde bulunabilir.

Sunucu ile etkileşim

mod_cache modülü CacheQuickHandler yönergesinin değerine bağlı olarak iki olası yerde sunucuya bağlanır:

Çabuk eylem aşaması

Bu aşama çok erken gerçekleşen bir aşama olup isteğin işlenmesi sırasında isteğin çözümlenmesinin hemen sonrasıdır. İçerik önbellekte mevcutsa hemen sunulur ve geri kalan istek işleme işlemi iptal edilir.

Bu senaryoda önbellek sunucunun önüne vidalanmış gibi davranır.

Sunucuda gerçekleşecek bir dizi işlemin büyük çoğunluğunun yapılmadan geçilmesi nedeniyle bu en yüksek başarımlı kiptir. Bu kip ayrıca, sunucu işlemlerinin kimlik doğrulama ve yetkilendirme aşamalarının da yapılmadan geçilmesini sağlar. Bu bakımdan bu kip seçilirken bu durum dikkate alınmalıdır.

"Authorization" başlığı içeren istekler (örneğin, HTTP Temel Kimlik Kanıtlaması gibi) mod_cache bu kipte çalışırken önbelleğe alınmadıkları gibi önbellekten bir işleme de sokulmazlar.

Normal eylem aşaması

Bu aşama geç bir aşama olup, isteğin tamamen işlenmesinin sonrasıdır.

Bu senaryoda önbellek sunucunun arkasına vidalanmış gibi davranır.

Bu kip en esneğidir. Önbelleğin, süzme zincirinin hassas olarak denetlenen bir noktasında oluşması sağlanabilir ve önbelleklenen içerik istemciye gönderilmeden önce süzülüp kişiselleştirilebilir.

URL önbellekte yoksa mod_cache modülü yanıtı önbelleğe kaydetme aşamasında süzgeç yığıtına bir süzgeç ekler ve geri çekilerek normal istek işlemlerinin devam etmesine izin verir. İçeriğin önbelleklenebilir olduğu saptanırsa içerik gelecekte sunulmak üzere önbelleğe kaydedilir, aksi takdirde içerik yok sayılır.

Önbellekteki içerik bayatsa, mod_cache modülü isteği bir koşullu istek haline getirir. Özgün sunucu normal bir yanıt verirse bu yanıt mevcut içeriğin yerine önbelleklenir. Özgün sunucu bir 304 Not Modified yanıtı verirse içerik tekrar taze olarak imlenir ve önbellekteki içerik süzgeç tarafından kaydedilmeden sunulur.

Önbelleğin Hızlandırılması

Bir sanal konak birçok farklı sunucu takma adından biri olarak bilindiği takdirde UseCanonicalName yönergesine On değeri atanmışsa önbellekten sunulan sayfa sayısında büyük bir artış olduğu görülür. Bunun sebebi içeriği sunan sanal konağın isminin önbellek anahtarının içinde kullanılmasıdır. Yönergeye On değerini atamak suretiyle çok isimli ve rumuzlu sanal konaklar için farklı önbellek girdileri oluşturulmaz, bunun yerine her meşru sanal konak için ayrı bir önbellek tutulur.

Tazelik Ömrü

Önbelleklenmek üzere tasarlanmış iyi biçimli bir içerik tazelik ömrünü Cache-Control başlığının max-age veya s-maxage alanlarıyla ya da bir Expires başlığını içererek bildirmelidir.

Aynı zamanda, özgün sunucunun tanımladığı tazelik ömrü, bir istemci tarafından istekte bir Cache-Control başlığı kullanılarak geçersiz kılınmak istenebilir. Bu durumda hangi tazelik ömrü daha kısaysa o geçerli olur.

Tazelik ömrü istekte veya yanıtta mevcut değilse öntanımlı bir tazelik ömrü kullanılır. Öntanımlı tazelik ömrü önbellekli içerik için bir saat olmakla birlikte CacheDefaultExpire yönergesi kullanılarak kolayca değiştirilebilir.

Bir yanıt Expires başlığını değil de Last-Modified başlığını içeriyorsa mod_cache tazelik ömrünü CacheLastModifiedFactor yönergesine bakarak saptar.

Yerel içerik için, ya da kendi Expires başlığını tanımlamayan uzak içerik için tazelik ömrünü max-age ve Expires ekleyerek hassas olarak ayarlamak için mod_expires kullanılabilir.

Tazelik ömrünün üst sınırı CacheMaxExpire yönergesi ile belirlenebilir.

Şartlı İstekler için Özlü Kılavuz

Önbellekteki içeriğin zaman aşımına uğrayıp bayat hale gelmesi, httpd’nin özgün isteği aktarmak yerine isteği değişikliğe uğratarak şartlı bir istek yapması sonucunu doğurur.

Özgün önbellekli yanıtta bir ETag başlığı mevcutsa, mod_cache modülü özgün sunucuya yapılan isteğe bir If-None-Match başlığı ekler. Özgün önbellekli yanıtta bir Last-Modified başlığı mevcutsa, mod_cache modülü özgün sunucuya yapılan isteğe bir If-Modified-Since başlığı ekler. Bunlardan birinin varlığı isteği koşullu yapar.

Bir koşullu istek özgün sunucu tarafından alındığında, özgün sunucu ETag veya Last-Modified başlığının isteğe uygun olarak değişip değişmediğine bakmalıdır. Değişmemişse, özgün sunucu kısa ve öz bir "304 Not Modified" yanıtı ile yanıt vermelidir. Bunun önbellekteki anlamı şudur: Eskimiş içerik hala tazedir ve içerik yeni tazelik ömrüne ulaşıncaya kadar sonraki isteklerde kullanılmalıdır.

İçerik değişmişse, bir şartlı istek yapılmamış gibi içeriğin kendisi sunulur.

Şartlı istekler çifte yarar sağlar. Birinci olarak, böyle bir istek özgün sunucuya yapılıyorsa ve iki içerik de aynıysa bunu saptamak kolay olur ve özkaynağın tamamını aktarma külfetinden kurtulunur.

İkinci olarak, iyi tasarlanmış bir özgün sunucu, koşullu istekler tam bir yanıt üretmekten önemli ölçüde ucuz olacak şekilde tasarlanmış olacaktır. Durağan dosyalar için bu genellikle stat() veya benzeri bir sistem çağrısıyla dosya boyutları ve değişiklik zamanına bakmak şeklinde gerçekleşir. Böylelikle, yerel içeriği bir değişiklik olmadığı takdirde önbellekten sunmak daha hızlı olacaktır.

Özgün sunucular koşullu istekleri desteklemek için her türlü çabayı göstermelidir. Ancak, koşullu istekler desteklenmiyorsa, özgün sunucu istek koşullu değilmiş gibi yanıt vermeli, önbellek ise, içerik değişmiş ve yani içerik önbelleğe kaydedilmiş gibi yanıt vermelidir. Bu durumda, önbellek basit bir iki durumlu (içerik ya tazedir ya da silinmiş) önbellek gibi davranacaktır.

Neler Önbelleklenebilir?

HTTP önbelleğin tarafından önbelleklenebilecek içerik RFC2616 Section 13.4 Response Cacheability belgesinde tanımlanmış olup, bunlar şöyle özetlenebilir:

  1. Önbellekleme bu URL ile etkin kılınabilmelidir. CacheEnable ve CacheDisable yönergelerine bakınız.
  2. Yanıtın HTTP durum kodu 200, 203, 300, 301 veya 410 olmalıdır.
  3. İstek bir HTTP GET isteği olmalıdır.
  4. Eğer yanıt bir "Authorization:" başlığı içeriyorsa ayrıca "Cache-Control:" başlığında da "s-maxage", "must-revalidate" veya "public" değerlerinden birini içermelidir, aksi takdirde önbelleklenmez.
  5. Eğer URL (GET yöntemi kullanan bir HTML formunun yaptığı gibi) bir sorgu dizgesi içeriyorsa yanıt, RFC2616’nın 13.9. bölümünde açıklandığı gibi bir "Expires:" başlığı içermedikçe veya "Cache-Control:" başlığının max-age veya max-age yönergesini içermedikçe yanıt içeriği önbelleğe alınmayacaktır.
  6. CacheIgnoreNoLastMod yönergesinin kullanımını gerektiren bir durum olmadıkça 200 durum koduna sahip bir yanıtın "Etag", "Last-Modified" ve "Expires" başlıklarından birini veya "Cache-Control:" başlığının "max-age" veya "s-maxage" yönergelerinden birini (en azından) içermesi gerekir.
  7. CacheStorePrivate yönergesinin kullanımını gerektiren bir durum olmadıkça yanıt "private" değerli bir "Cache-Control:" başlığı içerdiği takdirde yanıtın içeriği önbelleğe alınmayacaktır.
  8. Benzer şekilde, CacheStoreNoStore yönergesi kullanılmamışsa yanıt "no-store" değerli bir "Cache-Control:" başlığı içeriyorsa yanıt içeriği önbelleğe alınmayacaktır.
  9. Herşeyle eşleşen "*" değerli bir "Vary:" başlığı içeren bir yanıtın içeriği önbelleğe alınmaz.

Neler Önbelleklenmemeli?

İçerik zamana bağımlıysa ya da istek kısmen bile olsa HTTP uzlaşımıyla bağdaşmıyorsa önbelleğe alınmamalıdır. Bu içerik önbelleklenemeyeceğini Cache-Control başlığını kullanarak sunucuya bildirmelidir.

İçerik sıkça değişiyorsa, tazelik ömrü dakikalar veya saniyelerle ifade ediliyorsa, içerik yine de önbelleklenebilir. Ancak, tam yanıtların düzenli olarak üretilmemesinin temini için özgün sunucunun koşullu istekleri doğru olarak desteklemesi sağlanmalıdır.

İstemcinin sağladığı istek başlıklarına dayanarak değişen içerik, Vary yanıt başlığının akıllıca kullanımıyla önbelleklenebilir.

Değişken/Uzlaşımlı İçerik

Özgün sunucu, istekteki başlık değerlerine dayanarak farklı içeriklerle yanıt vermeye ayarlandığı takdirde, örneğin aynı URL'de farklı dillerde içerik sunmak gibi, HTTP'nin önbellekleme mekanizması aynı URL'de aynı sayfanın değişik sürümlerini önbelleklemeyi mümkün kılar.

Bu özgün sunucu tarafından bir Vary başlığı eklenerek yapılır. Bir sayfanın farklı sürümleri arasındaki farkları saptarken önbellek tarafından hangi başlıkların hesaba katılacağını Vary başlığı belirler.

Örneğin, bir yanıt şöyle bir başlık ile alınmışsa,

Vary: negotiate,accept-language,accept-charset

mod_cache sadece accept-language ve accept-charset başlıkları özgün istekle eşleşen önbellekli içeriği sunacaktır.

İçeriğin farklı sürümleri yan yana önbelleklenebilir. mod_cache modülü Vary başlığını kullanarak başlıkta listelenmiş istek başlıklarının uygun değerlerini saptar ve istemciye hangi sürümle yanıt verileceğine karar verir.

Disk Üzerinde Önbellekleme

mod_cache modülü önbelleği yönetmek için çeşitli depolama ortamlarına özgü gerçeklenimleri kullanır. Diske önbellekleme desteğini mod_cache_disk sağlar.

Tipik olarak modül şöyle yapılandırılır:

CacheRoot   "/var/cache/apache/"
CacheEnable disk /
CacheDirLevels 2
CacheDirLength 1

En önemlisi önbelleklenen dosyaların yerel olarak saklanması olup işletim sisteminin sağladığı bellekiçi önbelleklemeden de ayrıca faydalanılmış olur. Bu bakımdan, dosyalar disk üzerinde saklansa bile sıkça erişilen dosyalar işletim sistemi sayesinde aslında bellekten sunulmuş olacaklardır.

Önbellekte Saklamanın Anlamı

mod_cache_disk öğeleri önbellekte saklamak için istek yapılan URL’nin 22 karakterlik özetini oluşturur. Bu özet, çok sayıda URL’nin aynı özeti oluşturmaması için konak ismi, protokol, port ve varsa CGI argümanlarından başka Vary başlığında tanımlı elemanlardan oluşur.

Özeti oluşturan karakterler 64 karakterlik bir karakter kümesinden seçildiğinden oluşturulması olası farklı özet sayısı 64^22’dir. Örneğin, bir URL’nin xyTGxSMO2b68mBCykqkp1w gibi bir özeti olabilir. Bu özet, bu URL ile erişilen dosyalar önbellek içinde saklanırken dosya ismi öneki olarak kullanılır. Ancak bununla yetinilmez ve içerik CacheDirLevels ve CacheDirLength yönergelerinin değerlerine göre önce dizinlere ayrılır.

CacheDirLevels yönergesi kaç alt seviye dizin olacağını ve CacheDirLength her dizinde kaç karakter olacağını belirler. Örneğin, yukarıdaki özete sahip bir dosyanın isminin başına yukarıdaki yapılandırma örneğine uygun olarak /var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w gibi bir önek getirilebilirdi.

Bu tekniğin asıl amacı belli bir dizin içinde bulunabilecek dosyaların ve alt dizinlerin sayısını düşük tutmaktır. Bu sayının büyük olması çoğu işletim sisteminde başarımın düşmesine sebep olur. CacheDirLength yönergesi "1" değeriyle kullanıldığında her dizin altında en fazla 64 alt dizin veya dosya açılabilir. "2" değeriyle kullanıldığında ise bu sayı 64^2’ye yükselir ve böyle artarak gider. İyi bir sebebiniz olmadıkça CacheDirLength için değer olarak "1" belirtmenizi öneririz.

CacheDirLevels yönergesine atanacak değer önbellekte saklamayı düşündüğünüz olası dosya sayısı ile ilgilidir. Yukarıdaki örnekte olduğu gibi "2" değerini belirtirseniz, toplamda en fazla 4096 dizin oluşturulabilir. 1 milyon dosyanın önbelleklendiği bir durumda bu, her dizinde yaklaşık olarak 245 önbelleklenmiş URL demektir.

Her URL için önbellekte en az iki dosya saklanır. Biri genellikle URL hakkındaki temel verilerden oluşan ".header" dosyasıdır, diğeri ise sunulacak içeriğin bire bir kopyası olan ".data" dosyasıdır.

"Vary" başlığı üzerinden içeriğin uzlaşıldığı durumda URL için bir ".vary" dizini oluşturulur. Bu dizin her biri farklı bir uzlaşıma ait çok sayıda ".data" dosyası içerebilir.

Disk Önbelleğinin Bakımı

mod_cache_disk zaman aşımına uğrayan önbellekli içeriği silse de önbelleğin toplam boyu ve ne kadar boş bellek kaldığı hakkında bilgi vermez.

Bunun yerine httpd önbellek içeriğini düzenli aralıklarla temizleyebilmeniz için htcacheclean adında bir araç içerir. Önbellek için azami ne kadar yer kullanılacağının ve bunun üzerinde htcacheclean’i hangi sıklıkta çalıştırılacağının tespiti biraz karmaşık bir işlem olup uygun değerler genellikle deneme yanılma yoluyla bulunur.

htcacheclean iki işlem kipine sahiptir. Kalıcı bir artalan süreci olarak çalışabileceği gibi cron üzerinden belli aralıklarla da çalıştırılabilir. Çok büyük (onlarca GB) önbelleklerde htcacheclean’in işini bitirmesi 1 saatten fazla sürebileceğinden, cron ile çalıştırma durumunda aynı anda birden fazla kopyanın çalışıyor durumda olmaması için htcacheclean’in çalıştırılma aralığını iyi belirlemek gerekir.

Ayrıca, htcacheclean için uygun bir "nice" seviyesi seçilmesi önerilr. Böylece, sunucu çalışırken aracın ölçüsüz disk g/ç yapmasına sebebiyet verilmemiş olur.

Şekil 1: Önbelleğin büyümesi ve düzenli aralıklarla temizlenmesi.

mod_cache_disk ne kadar bellek kullanıldığı hakkında bilgi vermediğinden, htcacheclean'in bir temizliğin ardından yeterli bir büyüme alanı kalacak şekilde yapılandırılması temin edilmelidir.

İki durumlu Anahtar/Değer Paylaşımlı Nesne Önbellekleme

İlgili Modüller İlgili Yönergeler
  • mod_authn_socache
  • mod_socache_dbm
  • mod_socache_dc
  • mod_socache_memcache
  • mod_socache_shmcb
  • mod_ssl
  • AuthnCacheSOCache
  • SSLSessionCache
  • SSLStaplingCache

Apache HTTP sunucusu, SSL oturumları, kimlik doğrulama bilgileri gibi önbelleklenebilen özel bilgiler için socache arayüzü içinde düşük seviyeli bir paylaşımlı nesne önbelleğine sahiptir.

Her gerçeklenime uygun ek modüller de sağlanmıştır:

mod_socache_dbm
DBM tabanlı paylaşımlı nesne önbelleklemesi.
mod_socache_dc
Distcache tabanlı paylaşımlı nesne önbelleklemesi.
mod_socache_memcache
Memcache tabanlı paylaşımlı nesne önbelleklemesi.
mod_socache_shmcb
Paylaşımlı belleğe dayalı paylaşımlı nesne önbelleklemesi.

Kimlik Doğrulama Bilgilerinin Önbelleklenmesi

İlgili Modüller İlgili Yönergeler
  • mod_authn_socache
  • AuthnCacheSOCache

mod_authn_socache modülü kimlik doğrulama araçlarının yükünün hafifletilmesini, kimlik doğrulama sonucunun önbelleklenmesini sağlar.

SSL Oturumlarının Önbelleklenmesi

İlgili Modüller İlgili Yönergeler
  • mod_ssl
  • SSLSessionCache
  • SSLStaplingCache

mod_ssl modülü, oturum önbelleği ve önbellek zımbalaması sağlamak için socache arayüzünü kullanır.

Uzmanlaşmış Dosya Önbellekleme

İlgili Modüller İlgili Yönergeler
  • mod_file_cache
  • CacheFile
  • MMapFile

Dosya sisteminin yavaş olabildiği veya dosya tanıtıcılarının kullanımının pahalıya mal olduğu sistemlerde, sunucunun başlatılması sırasında dosyaların belleğe yüklenmesi seçeneği vardır.

Dosyaların açılmasının yavaş olduğu sistemlerde, dosyaların sunucunun başlatılması sırasında açılması ve dosya tanıtıcısını önbelleklenmesi seçeneği vardır. Bu seçeneklerin duruk dosyalara erişimin yavaş olduğu sistemlere de bir yardımı olabilir.

Dosya Tanıtıcı Önbelleklemesi

Bir dosyanın açılması işlemi, özellikle de ağ dosya sistemlerinde bulunan dosyalar için önemli bir gecikme kaynağı olabilir. Önbellekte, çok sunulan dosyaların kendilerinin değil, açık dosya tanıtıcılarının saklanması httpd’yi bu tür gecikmelerden koruyabilir. httpd’de tek türde dosya tanıtıcı önbelleklemesi yapılabilmektedir.

CacheFile yönergesi ile

httpd’de mevcut önbelleklemenin en temel şekli mod_file_cache tarafından sağlanan dosya tanıtıcı önbelleklemesidir. Bu önbellek türü dosyaların kendilerini değil açık dosya tanıtıcılarının bir listesini saklar. Dosyaların bu anlamda önbelleklenmesi, CacheFile yönergesi yapılandırma dosyasında belirtilerek sağlanabilir.

CacheFile yönergesi belirtilen dosyanın httpd başlatıldığında açılmasını ve dosya için yapılan sonraki her istekte bu dosya tanıtıcısının kullanılmasını sağlar.

CacheFile /usr/local/apache2/htdocs/index.html

Büyük miktarda dosyayı bu anlamda önbelleklemeyi tasarlıyorsanız işletim sisteminizin açık dosya tanıtıcılarının sayısı ile ilgili sınırlamasını uygun bir değere ayarlamanız gerekebilir.

CacheFile yönergesini kullandığınız takdirde dosya içeriğindeki değişiklikleri anında isteğe yansıtamazsınız. httpd dosyayı ilk başlatıldığındaki haliyle sunar.

Eğer httpd çalışırken dosya silinmişse httpd ilk başlatıldığındaki haline ilişkin dosya tanıtıcıyı sağlamaya ve dolayısıyla dosya içeriğini sunmaya devam edecektir. Yani, dosya silinmiş ve artık dosya sisteminde görünmüyor olsa bile httpd durdurulup dosya tanıtıcıları kapanmadıkça dosyaların silinmesiyle açılan yer serbest kalmayacaktır.

Sistem Belleğinde Önbellekleme

İçeriğin sistem belleğinden sunulması içerik sunmanın evrensel olarak en hızlı yoludur. Dosyaların bir disk denetleyiciden okunması ya da daha kötüsü uzak bir ağdan okunması bellekten okumayla karşılaştırılamayacak ölçüde yavaş işlemlerdir. Disk denetleyiciler genellikle fiziksel süreçleri denetlerler. Ağ erişimi ise band genişliği sınırlamalarından etkilenir. Halbuki bellek erişimi sadece nano saniyeler mertebesinde gerçekleşir.

Sistem belleği en pahalı saklama ortamı olması sebebiyle en verimli şekilde kullanımı önemlidir. Dosyaları sistem belleğinde saklamakla sistemin kullanabileceği bellek miktarını azaltmış olursunuz. İşletim sistemi önbelleklemesinde göreceğiniz gibi bu öyle basit bir konu değildir. httpd’nin kendi kullandığı belleğin bir kısmını önbellek olarak ayırırken çok fazla bellek kullanmamak önemlidir. Aksi takdirde işletim sistemi belleğin yetmediği noktada belleği diske takaslayacağından istenen başarım artışı sağlanamayacaktır.

İşletim Sistemi Önbelleklemesi

Günümüz iştetim sistemlerinin hemen hemen tamamında bellek içi dosya/veri saklama işlemlerini çekirdek yönetir. Bu güçlü bir özelliktir ve işletim sistemlerinin büyük çoğunluğu bunu böyle yapar. Örneğin, Linux’ta bir dosyanın ilk defa okunduğunda ve ikinci kez okunduğunda işlemcinin ne kadar meşgul edildiğine bakalım:

colm@coroebus:~$ time cat testfile > /dev/null
real 0m0.065s
user 0m0.000s
sys 0m0.001s
colm@coroebus:~$ time cat testfile > /dev/null
real 0m0.003s
user 0m0.003s
sys 0m0.000s

Küçük bir dosya için bile okuma süresi bakımından büyük fark ortaya çıkmaktadır. Bunun sebebi çekirdeğin dosya içeriğini bellek daha güncel amaçlar için lazım olana dek bellek içinde saklamasıdır.

Sisteminizde yeterince yedek bellek olduğundan eminseniz, bu önbellekte daha fazla dosya saklanacağından emin olabilirsiniz. Bundan, önbelleğin sistem belleğinde verimli biçimde tutulması için httpd’de ek bir yapılandırmaya gidilmesinin gerekmediği sonucu çıkarılabilir.

Bundan başka, işletim sistemi dosyaların değiştiği ve silindiği zamanları bildiğinden bu tür dosyaların içerikleri gerektiğinde önbellekten kendiliğinden silinmiş olur. Bellek içinde dosya saklarken dosyaların değiştirilme zamanlarını bilme olanağı olmadığından bu durum httpd’ye büyük yarar sağlar.

İşletim sisteminin dosyaların önbelleklenmesi için sağladığı bunca yarara ve başarım artışına karşın bellek içinde dosya önbelleklemenin httpd tarafından yerine getirilmesinin daha iyi olacağı bazı durumlar vardır.

MMapFile yönergesi ile

mod_file_cache modülü, bir durağan dosyanın içeriğini sunucunun başlatılması sırasında (mmap sistem çağrısıyla) belleğe eşlenmesini mümkün kılmak için MMapFile yönergesini sağlar. httpd bu dosyaya gelecek sonraki istekler için dosyanın bellekiçi içeriğini kullanacaktır.

MMapFile /usr/local/apache2/htdocs/index.html

CacheFile yönergesinde olduğu gibi bu dosyalarda httpd başlatıldıktan sonra yapılacak bir değişiklikten httpd’nin haberi olmayacaktır.

MMapFile yönergesi ayırdığı belleğin toplam miktarı ile ilgilenmez, dolayısıyla yönergenin aşırı kullanımından kaçınmalısınız. httpd’nin çocuk süreçlerinin her biri bu belleğin kendilerine ait birer kopyasını yapacağından belleğe eşlenen dosyaların çok yer kaplamaması büyük önem taşımaktadır; aksi takdirde işletim sistemi belleği diske takaslayacağından beklenen fayda sağlanamayacaktır.

Güvenlik Kaygıları

Erişim Denetimi ve Yetkilendirme

CacheQuickHandler yönergesine On değerinin atandığı öntanımlı durumda mod_cache kullanımı, daha çok sunucunun önüne vidalanmış önbelleklemeli bir karşı vekile sahip olmak gibidir. Özgün sunucunun bir harici önbellekmiş gibi sorgulanmasını gerektirmeyen tüm istekler önbellekleme modülü tarafından karşılanacaktır. Bu durum httpd'nin güvenlik modelini büyük ölçüde değiştirir.

Olası .htaccess dosyalarının dosya sisteminin tamamında taranması çok pahalı bir işlem olduğundan mod_cache, (işlemi hızlandırmak için) önbelleğe almanın temel amacını kısmen gözardı ederek, önbellekteki içeriğin sunumu için gerekli yetkilendirmenin olup olmadığı konusunda bir karar üretmez. Başka bir deyişle, eğer mod_cache bir kısım içeriği önbelleğe almışsa içerik zaman aşımına uğramadığı sürece bu içerik önbellekten sunulacaktır.

Örneğin, yapılandırmanız bir özkaynağa IP adresine göre erişime izin veriyorsa bu içeriğin önbelleğe alınmayacağından emin olmalısınız. Bunu CacheDisable yönergesini veya mod_expires modülünü kullanarak yapabilirsiniz. Bunu yapmaz, olayı kendi haline bırakırsanız mod_cache bir karşı vekil gibi çalışarak sunulan her içeriği önbelleğe alacak ve hangi IP adresinden gelirse gelsin her istemciye bunu sunacaktır.

CacheQuickHandler yönergesine Off atandığı takdirde, istek işleme aşamalarının tamamı yerine getirilir ve güvenlik modeli değişmeden kalır.

Yerel İstismarcılar

Son kullanıcılarıın isteklerine önbellekten hizmet sunulduğundan önbelleğin kendisi içerikle etkileşime geçmek isteyenlerin veya içeriği tahrif etmek isteyenlerin hedefi haline gelebilir. httpd’yi çalıştıran kullanıcı tarafından her zaman önbelleğe yazılabileceğini akıldan çıkarmamak önemlidir. Bu durumda alışılmışın tersine tüm içeriğin Apache kullanıcısı tarafından yazılamamasının sağlanması önerilir.

Eğer Apache kullanıcısı, örneğin bir CGI sürecindeki açık nedeniyle tehlikeye atılırsa, önbellek hedef alınabilir. mod_cache_disk kullanılırken önbellekteki bir öğeyi değiştirmek veya önbelleğe yeni bir öğe eklemek görece daha kolaydır.

Bu risk, Apache kullanıcısını kullanan diğer saldırı türleriyle karşılaştırıldığında daha yüksektir. mod_cache_disk kullanıyorsanız şunları aklınızdan çıkarmayın: (1) httpd güvenlik güncellemelerini takip edin ve sunucunuzu buna göre güncelleyin. (2) Mümkünse suEXEC kullanarak CGI süreçlerini Apache kullanıcısı olmayan bir kullanıcının aidiyetinde çalıştırın.

Önbellek Zehirlenmeleri

httpd bir önbellekli vekil sunucu olarak çalıştığında önbellek zehirlenmesi adı verilen sorunla karşılaşılma olasılığı vardır. Önbellek zehirlenmesi, vekil sunucunun özgün sunucudan yanlış (ve genellikle istenmeyen) içerik almasına sebep olan bir saldırı türünü betimlemek için yaygın olarak kullanılan bir terimdir.

Örneğin httpd’nin çalıştığı sistemin kullandığı DNS sunucuları DNS önbellek zehirlenmesinden etkilenebilecek durumdaysa, bir saldırgan httpd’nin istekleri almak için başvuracağı kaynak sunucunun yerini değiştirebilir. Diğer bir örnek, HTTP istek kaçakçılığı adı verilen bir saldırı türüdür.

Bu belge HTTP istek kaçakçılığını derinliğine incelenmesi için uygun yer değildir (böyle kaynaklara arama motorunuzla erişebilirsiniz). Bununla birlikte, vekil tarafından kaynak sunucudan alınan içeriği tamamen denetim altına almak amacıyla kaynak sunucudaki bir açığı istismar etmeye yönelik bir dizi istek yapılabileceğinin olasılık dahilinde olduğunu bilmenizde yarar vardır.

Hizmet Reddi / Önbelleğin Engellenmesi

Vary mekanizması aynı URL'nin çok sayıda sürümünün yan yana önbelleklenmesini mümkün kılar. İstemci tarafından sağlanan başlık değerlerine bağlı olarak, önbellek istemciye gönderilecek doğru yanıtı bulacaktır. Normal kullanımda olası değerlerin çok geniş olduğunun bilindiği durumda bir başlığı (örn, User-Agent) değişikliğe uğratma çabası bu mekanizmayı bir sorun haline getirebilir. Sitenin tanınırlığına bağlı olarak aynı URL'nin binlerce hatta milyonlarca önbellek girdisi oluşabilir ve bunlar önbellekteki diğer girdilerin yerini alabilir.

Diğer yandan, belli bir özkaynağın URL'sinin her istekte değiştirilmesi ihtiyacı ortaya çıkabilir. Bu normalde URL dizgesine bir "cachebuster" dizgesi eklenerek yapılır. Bu içerik sunucu tarafından anlamlı bir tazelik ömrüyle önbelleklenebilir olarak imlenmişse bu girdiler kısa zamanda önbellekteki meşru girdilerin yerini alabilir. mod_cache modülü bunun önlenmesi için CacheIgnoreURLSessionIdentifiers yönergesine sahipse de bu yönerge, yoldaki vekillerin veya tarayıcı önbelleklerinin aynı hizmet reddi saldırısına maruz kalmamaları için dikkatle kullanılmalıdır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Sunucu Genelinde Yapılandırma - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Sunucu Genelinde Yapılandırma

Bu belgede core modülü ile sağlanan ve sunucunun temel işlemlerini yapılandırmakta kullanılan yönergelerden bazıları açıklanmıştır.

Sunucu Kimliği

İlgili Modüller İlgili Yönergeler
  • ServerName
  • ServerAdmin
  • ServerSignature
  • ServerTokens
  • UseCanonicalName
  • UseCanonicalPhysicalPort

ServerAdmin ve ServerTokens yönergeleri, hata iletileri gibi sunucu tarafından üretilen belgelerde sunucu ile ilgili hangi bilgilerin sunulacağını belirlerler. ServerTokens yönergesi sunucunun HTTP yanıt başlığı alanının değerini belirler.

ServerName, UseCanonicalName ve UseCanonicalPhysicalPort yönergeleri, sunucu tarafından, özüne yönelik URL’leri nasıl oluşturacağını saptamak için kullanılır. Örneğin bir istemci bir dizin isteğinde bulunurken URL’nin sonuna bölü çizgisi eklemese bile Apache httpd’nin istemciyi bölü çizgisi ile bitirilmiş URL yoluna yönlendirmesi gerekir; böylece istemci belge içindeki göreli bağlantıları doğru şekilde çözümleyebilir.

Dosyaların Yerleri

İlgili Modüller İlgili Yönergeler
  • CoreDumpDirectory
  • DocumentRoot
  • ErrorLog
  • Mutex
  • PidFile
  • ScoreBoardFile
  • ServerRoot

Bu yönergeler Apache httpd’nin doğru işlem yapması için gereksinim duyduğu çeşitli dosyaların yerlerini belirlerler. Bölü çizgisi (/) ile başlamayan dosya yolları kullanıldığında bu dosyaların yerlerinin ServerRoot yönergesinde belirtilen dizine göre belirtildiği varsayılır; root olmayan kullanıcılar tarafından yazılabilen dosya yollarına dosya yerleştirmemeye dikkat ediniz. Bu konuda daha ayrıntılı bilgi edinmek için güvenlik ipuçları belgesine bakınız.

Özkaynak Kullanımının Sınırlanması

İlgili Modüller İlgili Yönergeler
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldsize
  • LimitRequestLine
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • ThreadStackSize

LimitRequest* yönergeleri, Apache httpd’nin istemcilerden gelen istekleri okumak için kullanacağı özkaynakların miktarları ile ilgili sınırlamalar koymak için kullanılırlar. Bu değerleri sınırlamak suretiyle bazı hizmet reddi saldırılarının etkileri azaltılabilir.

RLimit* yönergeleri ise Apache httpd’nin çocuk süreçleri tarafından çatallanabilen özkaynakların miktarlarını sınırlamakta kullanılırlar. Özellikle de CGI betikleri ve SSI çalıştırma komutları tarafından kullanılan özkaynakları denetlemekte kullanılırlar.

ThreadStackSize yönergesi bazı platformlarda yığıt boyutunu denetim altında tutmak için kullanılır.

Gerçeklenimle ilgili Seçimler

İlgili Modüller İlgili Yönergeler
  • Mutex

Mutex yönergesi, APR'nin öntanımlı seçimi ile ilgili işlevsel ve başarımsal sorunlarına çare bulmada ilgili gerçeklenimi mutex'ler için değiştirmekte kullanılabilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Günlük Dosyaları - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Günlük Dosyaları

Bir HTTP sunucusunu verimli şekilde yönetebilmek için oluşabilecek sorunlardan başka sunucunun başarımı ve etkinliği hakkında da bazı geri bildirimler almak gerekir. Apache HTTP Sunucusu çok kapsamlı ve esnek bir günlükleme yeteneğine sahiptir. Bu belgede sunucunun günlükleme yeteneğini nasıl yapılandıracağınızdan ve günlük kayıtlarını nasıl yorumlayacağınızdan bahsedilecektir.

Giriş

İlgili Modüller İlgili Yönergeler
  • mod_log_config
  • mod_log_forensic
  • mod_logio
  • mod_cgi

Apache HTTP Sunucusu, isteğin ilk alınışından itibaren, URL eşleme işlemleri, bağlantının son çözümlemesi ve bu işlemler sırasına ortaya çıkan hatalar da dahil olmak üzere sunucunuzda meydana gelen herşeyi günlüklemek için çok çeşitli mekanizmalar içerir. Buna ek olarak, günlükleme yetenekleri sağlayan üçüncü parti modüller de kullanılabilir veya mevcut günlük dosyalarına girdiler enjekte edilebilir. Ayrıca, CGI programları, PHP betikleri ve benzerleri sunucu hata günlüğüne kendi iletilerini gönderebilirler.

Bu belgede Apache HTTP Sunucusunun standart parçası olan günlükleme modülleri hakkında bilgi verilecektir.

Güvenlik Uyarısı

Apache httpd’nin günlük dosyalarını yazdığı dizine yazabilen birinin sunucuyu başlatan kullanıcı kimliğine (bu genellikle root olur) erişim kazanabileceğine hemen hemen kesin gözüyle bakılabilir. Sonuçlarının neler olacağını kestiremiyorsanız günlüklerin yazıldığı dizinde hiç kimseye yazma erişimi vermeyin; ayrıntılı bilgi için güvenlik ipuçları belgesine bakınız.

Buna ilaveten, günlük dosyaları istemci tarafından sağlanmış bilgiler de içerebilir. Bu nedenle, kötü niyetli istemcilerin günlük dosyalarına denetim karakterleri girmeleri olasılığına karşı ham günlükler ele alınırken dikkatli olunmalıdır.

Hata Günlüğü

İlgili Modüller İlgili Yönergeler
  • core
  • ErrorLog
  • ErrorLogFormat
  • LogLevel

İsmi ve yeri ErrorLog yönergesi ile belirtilen sunucu hata günlüğü, en önemli günlük dosyasıdır. Apache httpd tarafından istekler işlenirken saptanan hatalar ve tanı bilgileri bu dosyaya gönderilir. Sunucuyu başlatırken veya sunucu çalışırken bir sorunla karşılaşıldığında, neyin yanlış gittiğini öğrenmek için bakılacak ilk yer burasıdır. Günlük kaydı çoğunlukla sorunun nasıl düzeltileceği ile ilgili ayrıntıları da içerir.

Hata günlüğü normal olarak bir dosyaya yazılır (genellikle, dosyanın ismi Unix sistemlerinde error_log, OS/2 ve Windows’ta ise error.log’dur). Ayrıca, Unix sistemlerinde sunucunun hataları syslog’a veya borulamak suretiyle bir programa aktarması da mümkündür.

Hata günlüğünün biçemi ErrorLogFormat yönergesi ile belirlenir. Bu yönergeyi kullanarak günlüklenen değerleri özelleştirebilirsiniz. Bir biçem belirtmezseniz öntanımlı biçem kullanılır. Örnek tipik bir hata iletisi içermektedir:

[Fri Sep 09 10:42:29.902022 2011] [core:error] [pid 35708:tid 4328636416] [client 72.15.99.187] Dosya yok: /usr/local/apache2/htdocs/favicon.ico

Günlük girdisinin ilk öğesi iletinin yazıldığı tarih ve saatten oluşur. İkincisi iletiyi üreten modülün ismi (bu durumda: core) ile raporlanan bilginin önem derecesini belirtir. Bunu varsa sürecin kimliği ve yine varsa evre kimliği izler. Sonraki öğe hatanın üretilmesine sebep olan istemcinin IP adresini içerir. Kalanı iletinin kendisidir (duruma bakılırsa bir dosyaya yapılan istek yerine getirilememiş).

Hata günlüğünde görünebilecek ileti çeşitliliği oldukça fazladır. Çoğu yukarıdaki örneğin benzeridir. Hata günlüğü ayrıca, CGI betiklerinin hata ayıklama çıktılarını da içerir. Bir CGI betiği tarafından standart hataya (stderr) yazılan her türlü bilgi doğrudan hata günlüğüne kopyalanır.

Hata günlüğüne ve erişim günlüğüne %L dizgeciği konularak erişim günlüğündeki girdi ile hata günlüğündeki girdiyi ilişkilendirecek bir günlük girdisi kimliği oluşturulabilir. mod_unique_id yüklüyse günlük girdisi kimliği olarak onun eşsiz istek kimliği de kullanılır.

Sunucuyu denerken olası sorunlara karşı hata günlüğünü sürekli izlemelisiniz. Unix sistemlerinde bunu şöyle bir komutla sağlayabilirsiniz:

tail -f error_log

Modüllere göre günlükleme

LogLevel yönergesi, günlük iletisinin üretilmesine sebep olan modüle bağlı bir önem seviyesi belirleyebilmenizi sağlar. Bu yolla sorun yaşadığınız modülle ilgili günlük musluklarını sonuna kadar açabiliri ek olarak ilgilendiğiniz diğer modüllerle ilgili ayrıntıları da edinebilirsiniz. Özellikle mod_proxy veya mod_rewrite gibi modüllerde yapılmak isteneni denerken neler olup bittiğini ayrıntılarıyla bilmek istediğiniz durumlarda kullanışlıdır.

Bunu LogLevel yönergesinde modülün ismini belirterek yapabilirsiniz:

LogLevel info rewrite:trace5

Bu satırla ana LogLevel info'ya ayarlanırken mod_rewrite için musluk trace5 seviyesine kadar açılmaktadır.

Bu yönerge, Apache HTTP Sunucusunun evvelki sürümlerinde mevcut olan RewriteLog gibi günlükleme modüllerinin yerini almıştır.

Erişim Günlüğü

İlgili Modüller İlgili Yönergeler
  • mod_log_config
  • mod_setenvif
  • CustomLog
  • LogFormat
  • SetEnvIf

Sunucu erişim günlüğü sunucu tarafından işleme alınan tüm istekleri kaydeder. Erişim günlüğünün yeri ve içeriği CustomLog yönergesi ile belirlenir. LogFormat yönergesi ile günlük içeriğini kişiselleştirmek mümkündür. Bu bölümde sunucunun bilgileri erişim günlüğüne kaydetmesi için nasıl yapılandırılacağından bahsedilecektir.

Şüphesiz, bilginin erişim günlüğünde saklanması günlük yönetiminde ilk adımı oluşturur. Sonraki adım yararlı istatistikleri üretmek için bu bilgiyi incelemektir. Günlük incelemesi bu belgenin kapsamına dahil değildir ve aslında bu işlem sunucunun yaptığı işlerden biri değildir. Bu konu ve günlük incelemesi yapan uygulamalar hakkında daha ayrıntılı bilgi edinmek için dmoz.org veya Yahoo’ya bakınız.

Apache httpd’nin çeşitli sürümlerinde erişim günlüklerini denetlemek için kullanılan diğer modüller ve yönergeler arasında mod_log_referer, mod_log_agent modülleri ve TransferLog yönergesi sayılabilir. Artık, daha eski tüm diğer yönergelerin işlevselliklerini bir araya toplayan CustomLog yönergesi kullanılmaktadır.

Erişim günlüğünün girdi biçemi kolayca isteğe göre düzenlenebilmektedir. Biçemi belirtmekte kullanılan biçem dizgesi, C tarzı printf(1) biçem dizgesini andırır. Sonraki bölümlerde bazı örneklere yer verilmiştir. Biçem dizgesini oluşturan belirteçlerin tam listesi için mod_log_config belgesinin Günlük Girdilerinin Kişiselleştirilmesi bölümüne bakınız.

Ortak Günlük Biçemi (OGB)

Erişim günlüğü için sıklıkla kullanılan bir yapılandırma:

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

İlk satırda belli bir biçem dizgesi için common diye bir takma ad tanımlanmaktadır. Biçem dizgesi, sunucuya hangi belli bir bilgi parçalarını günlükleyeceğini söyleyen % imli biçem belirteçlerinden oluşur. Biçem dizgesine ayrıca dizgesel sabitler de yerleştirilebilir ve bunlar erişim günlüğüne oldukları gibi kopyalanırlar. Biçem dizgesi içinde çift tırnak karakteri (") biçem dizgesini vaktinden önce sonlandırmaması için ters bölü çizgisi ile öncelenmelidir. Biçem dizgesi ayrıca, satır sonlarını belirtmek için "\n" ve sekmeleri belirtmek için "\t" denetim karakterlerini de içerebilir.

CustomLog yönergesi evvelce tanımlanmış bir takma adı kullanarak yeni bir günlük dosyası tanımlar. Erişim günlüğünün dosya ismi bölü çizgisi ile başlamadıkça dosya yolunun ServerRoot değerine göreli olduğu varsayılır.

Yukarıdaki yapılandırma günlük dosyasına girdileri Ortak Günlük Biçemi (Common Log Format) adı verilen standart biçemde yazar. Bu standart biçem başka HTTP sunucuları tarafından da kullanılır ve çoğu günlük inceleme yazılımı tarafından tanınır. Ortak Günlük Biçeminde üretilen günlük girdileri şöyle görünür:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326

Bu günlük girdisini parça parça açıklayalım:

127.0.0.1 (%h)
Bu, sunucuya istek yapan istemcinin (uzak konağın) IP adresidir. Eğer HostnameLookups yönergesine On değeri atanmışsa sunucu bu IP adresi için DNS sorgusu yapacak ve IP adresi yerine bulduğu konak ismini yazmaya çalışacaktır. Bununla birlikte, bu işlem sunucuyu epeyce yavaşlattığından önerilmemektedir. Konak isimlerini saptamak için en iyisi günlük girdilerini logresolve gibi bir günlük işlemcisinden geçirmektir. Burada raporlanan IP adresi doğrudan istemcinin IP adresi olmayabilir. Eğer sunucu ile istemci arasında bir vekil sunucu varsa bu IP adresi, vekil sunucunun IP adresi olacaktır.
- (%l)
Çıktıdaki bir "tire" imi istenen bilgi parçasının mevcut olmadığı anlamına gelir. Bu durumda, mevcut olmayan bilgi istemci makine üzerinde identd tarafından belirlenen istemcinin RFC 1413 kimliğidir. Bu bilgi oldukça güvenilmezdir ve sıkıca denetlenen iç ağlar haricinde hemen hemen asla kullanılmamalıdır. Apache, IdentityCheck yönergesine On değeri atanmış olmadıkça bu bilgiyi saptamaya uğraşmaz.
frank (%u)
Bu, belge isteğinde bulunan kişinin HTTP kimlik doğrulamasıyla saptanan kullanıcı kimliğidir. Bu değer CGI betiklerine REMOTE_USER ortam değişkeni ile sağlanır. Eğer istek için durum kodu 401 ise (aşağıya bakınız) henüz kullanıcının kimliği doğrulanmamış olacağından bu değere güvenilmemelidir. Eğer belge parola korumalı değilse günlüğün bu kısmı da yukarıdaki gibi "-" olacaktır.
[10/Oct/2000:13:55:36 -0700] (%t)
İsteğin alındığı tarih ve saat. Biçemi şöyledir:

[gün/ay/yıl:saat:dakika:saniye dilim]
gün    = 2 hane
ay     = 3 harf
yıl    = 4 hane
saat   = 2 hane
dakika = 2 hane
saniye = 2 hane
dilim  = (`+' | `-') 4 hane

Günlük biçem dizgesinde zaman gösterim biçemini %{biçem}t şeklinde belirtmek de mümkündür. Buradaki biçem dizgesi, stardart C kütüphanesindeki strftime(3) işlevi için tanımlanmış biçem belirteçleriyle veya desteklenen özel belirteçlerle oluşturulabilir. Ayrıntılı bilgi için mod_log_config biçem dizgelerine bakın.

"GET /apache_pb.gif HTTP/1.0" (\"%r\")
İstemciden alınan istek satırının çift tırnaklar arasında gösterilmesi istenmiştir. İstek satırı en yararlı bilgi parçalarını içerir. Birincisi, istemci tarafından kullanılan yöntem GET’miş. İkinci olarak istemci /apache_pb.gif dosyasını istemiş ve üçüncü olarak istemci HTTP/1.0 protokolünü kullanmış. İstek satırının bazı parçalarını bağımsız olarak da günlüklemek mümkündür. Örneğin, "%m %U%q %H" dizgesi, yöntem, yol, sorgu dizgesi ve protokolü kaydedecektir; bu dizge "%r" biçem belirtecinin tek başına yaptığı işi yapar.
200 (%>s)
Bu, sunucunun istemciye gönderdiği durum kodudur. İsteğin başarıyla yerine getirilip getirilmediğini gösterdiği için bu bilgi çok değerlidir. Durum kodu 2 ile başlıyorsa istek başarıyla yerine getirilmiştir, 3 ile başlıyorsa yönlendirilmiştir, 4 ile başlıyorsa istemci tarafında bir hata oluşmuştur, 5 ile başlıyorsa sunucuda bir hata oluşmuştur. Olası hata kodlarının tam listesi RFC2616 Hiper Metin Aktarım Protokolünün 10. bölümünde bulunabilir.
2326 (%b)
Son parça istemciye döndürülen nesnenin yanıt başlığı hariç uzunluğudur. Eğer istemciye bir içerik döndürülmemişse bu değer "-" olacaktır. Bunun yerine günlüğe "0" yazdırmak için %B belirtecini kullanınız.

Birleşik Günlük Biçemi

Sıklıkla kullanılan diğer bir biçem dizgesi Birleşik Günlük Biçemi (Combined Log Format) olup şöyle kullanılabilir:

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
CustomLog log/access_log combined

Bu biçem ilaveten 2 alan içermesi dışında Ortak Günlük Biçemi ile aynıdır. İlave alanların ikisi de %{başlık}i biçeminde olup buradaki başlık, HTTP isteğindeki başlık alanlarından biridir. Bu biçemin kullanıldığı bir erişim günlüğü girdisi şöyle olurdu:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)"

Ek alanlar:

"http://www.example.com/start.html" (\"%{Referer}i\")
HTTP istek başlığı "Referer". İstemcinin raporladığı isteğin kaynaklandığı URI. (Bu isteğin yapılmasını sağlayan bağlantıyı içeren URL veya istek bir sayfanın bileşenleri ile ilgiliyse istenen sayfanın URL’si olabilir.)
"Mozilla/4.08 [en] (Win98; I ;Nav)" (\"%{User-agent}i\")
Tarayıcı kimliğini içeren HTTP istek başlığı. Bu istemcinin tarayıcısının raporladığı kendi tanıtım bilgisidir.

Çok Sayıda Erişim Günlüğü

Yapılandırma dosyasında çok sayıda CustomLog yönergesi kullanarak çok sayıda erişim günlüğü kolayca oluşturulabilir. Örneğin aşağıdaki yönergelerle 3 tane erişim günlüğü oluşturulacaktır. İlki temel OGB bilgisini içerirken diğer ikisi isteğin kaynaklandığı yeri ve tarayıcı kimliğini içerir. Son iki CustomLog satırı ayrıca, ReferLog ve AgentLog yönergelerinin etkilerinin nasıl taklit edileceğini de göstermektedir.

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
CustomLog logs/referer_log "%{Referer}i -> %U"
CustomLog logs/agent_log "%{User-agent}i"

Bu örnek ayrıca, LogFormat yönergesi ile bir takma ad tanımlamanın şart olmadığını da göstermektedir. Günlük biçemi doğrudan CustomLog yönergesinde belirtilebilir.

Şarta Bağlı Günlükler

Bazı durumlarda istemcinin yaptığı isteğe bağlı olarak erişim günlüğünde belli girdilerin dışlanması gerekebilir. Bu, ortam değişkenleri sayesinde kolayca yerine getirilebilir. Önce isteğin belli koşulları sağladığını belirten bir ortam değişkeni ataması yapılır. Bu işlem SetEnvIf yönergesi ile yapılır. Sonra da, ortam değişkenine bağlı olarak isteklerin günlüğe dahil edilip edilmeyeceği CustomLog yönergesinin env= deyimi kullanılarak belirtilir. Bazı örnekler:

# yerel konaktan kaynaklanan istekleri imleyelim
SetEnvIf Remote_Addr "127\.0\.0\.1" kaydetme
# robots.txt dosyası isteklerini imleyelim
SetEnvIf Request_URI "^/robots\.txt$" kaydetme
# Kalanları günlüğe kaydedelim
CustomLog logs/access_log common env=!kaydetme

Başka bir örnek olarak, Türkçe belge isteklerini bir dosyaya diğer dillerdeki istekleri başka bir dosyaya kaydedelim.

SetEnvIf Accept-Language "tr" turkce
CustomLog logs/turkce_log common env=turkce
CustomLog logs/diger_diller_log common env=!turkce

Bir arabellekleme senaryosuna arabelleğin verimli kullanılıp kullanılmadığını bilmek isteyelim. Bu basitçe şöyle yapılabilir:

SetEnv CACHE_MISS 1
LogFormat "%h %l %u %t "%r " %>s %b %{CACHE_MISS}e" common-cache
CustomLog logs/access_log common-cache

mod_cache önce mod_env modülünü çalıştıracak ve başarılı olunduğu takdirde içeriği onsuz teslim edecektir. Bu durumda arabellek kaybı 1 olarak günlüklenirken arabellek sunumu - olarak günlüklenecektir.

env= sözdizimine ek olarak, LogFormat HTTP yanıt kodudaki koşul değerlerini günlüklemeyi de destekler:

LogFormat "%400,501{User-agent}i" browserlog
LogFormat "%!200,304,302{Referer}i" refererlog

Bu örnekte, HTTP durum kodu 400 veya 501 ise User-agent başlığı günlüklenecektir. Aksi takdirde, günlüğe bir "-" yazılacaktır. Benzer şekilde ikinci örnekte, HTTP durum kodu 200, 204 veya 302 değilse (durum kodlarının öncesindeki "!" imine dikkat) Referer başlığı günlüklenecektir.

Koşulaa bağlı günlük kaydının çok esnek ve güçlü olabileceğini göstermiş olsak da günlük içeriğini denetlemenin tek yolu bu değildir. Günlük dosyaları sunucu etkinliğini eksiksiz olarak kaydedebildikleri takdirde daha yararlı olurlar. Günlük dosyalarını sonradan işleme tabi tutarak istenmeyen girdileri kaldırılmış bir kopya almak hem kolay hem de daha yararlıdır.

Günlük Çevrimi

Yükü ağır sunucularda günlük dosyalarına kaydedilen bilginin miktarı çok büyük boyutlara ulaşabilir. 10.000 istek içeren bir erişim günlüğü yaklaşık 1MB yer kaplar. Etkin günlük dosyasını belirli aralıklarla değiştirmek veya silmek gerekebilir. Apache httpd çalışırken dosyayı sürekli açık tuttuğu ve yazdığı için bu işlem sunucu çalışırken yapılamaz. Bu bakımdan, günlük dosyası değiştirildikten veya silindikten sonra yeni dosyanın açılması için sunucunun yeniden başlatılması gerekir.

Nazikçe yeniden başlatmak suretiyle sunucunun, mevcut ve bekleyen bağlantıları kaybetmeden yeni günlük dosyalarını açması sağlanabilir. Bununla birlikte, bu işlem sırasında sunucunun eski isteklere sunumu bitirene kadar eski günlük dosyalarına yazmaya devam edebilmesi gerekir. Bu bakımdan, yeniden başlatmanın ardından eski günlük dosyaları üzerinde bir işlem yapmadan önce biraz beklemek gerekir. Günlük dosyalarını döndürürken kullanılan senaryolarda genellikle eski günlük dosyaları yer kazanmak için sıkıştırılırlar:

mv access_log access_log.old
mv error_log error_log.old
apachectl graceful
sleep 600
gzip access_log.old error_log.old

Günlük çevrimi yapmanın başka bir yolu da sonraki bölümde açıklandığı gibi borulu günlükler kullanmaktır.

Borulu Günlükler

Apache httpd hata ve erişim günlüklerini doğrudan bir dosyaya yazmak yerine bir boru üzerinden başka bir sürece yazabilir. Bu yetenek ana sunucuya herhangi bir kod eklemeksizin günlükleme esnekliğini şaşırtıcı derecede arttırır. Günlükler boruya yazılmak istenirse dosya ismini boru karakteriyle ("|") değiştirip ardına günlük girdilerini standart girdisinden kabul edecek programın ismini eklemek yeterlidir. Apache httpd başlatıldığı zaman borulu günlük işlemini de başlatacaktır. Eğer sunucu çalışırken günlükleri kabul eden süreç çökerse Apache httpd bu programı yeniden başlatır. (Bu son özelliği sebebiyle bu tekniğe “güvenilir borulu günlükleme” adını veriyoruz.)

Borulu günlük süreçleri ana Apache httpd süreci tarafından başlatılır ve bu süreçler ana Apache httpd sürecinin kullanıcı kimliğini miras alırlar. Yani borulu günlükleme programları aslında root tarafından çalıştırılmış gibi olur. Bu bakımdan, bu programları basit ve güvenilir kılmak çok önemlidir.

Borulu günlüklerin önemli kullanım alanlarından biri de sunucuyu yeniden başlatmak gerekmeksizin günlük çevrimini mümkün kılmaktır. Apache HTTP sunucusu bu amaçla kullanılmak üzere rotatelogs diye bir program içerir. Örneğin, günlükleri 24 saatte bir döndürmek isterseniz bunu şöyle yapabilirsiniz:

CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common

Borunun diğer ucundaki süreci başlatacak komutun tırnak içine alındığına dikkat ediniz. Bu örnekler erişim günlüğü için verilmişse de aynı teknik hata günlüğü için de kullanılabilir.

Hariçten bir uygulama olarak cronolog isminde buna benzer ancak çok daha esnek bir program daha vardır.

Borulu günlükler de şarta bağlı günlükleme kadar güçlü olmakla beraber çevrimdışı ardıl işlemler gibi daha basit çözümler için kullanılmamalıdır.

Öntanımlı olarak borulu günlük süreci bir kabuk kullanmadan çalıştırılır. Kabuk kullanarak (genelde /bin/sh -c ile) yapılmak istenirse "|" yerine "|$" kullanılır:

# Kabuk kullanarak "rotatelogs" çalıştırmak
CustomLog "|$/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common

Bu, Apache 2.2 için öntanımlı davranıştı. Kabuk özelliklerine bağlı olarak, yeniden başlatma sırasındaki sinyal işleme sorunları ve günlük borulama uygulamasının yaşam süresi için ek bir kabuk süreci ile sonuçlanabilir. Apache 2.2 ile uyumluluk açısından "||" gösterimi de desteklenmekte olup "|" kullanımına eşdeğerdir.

Windows'ta yığın alanı

Windows'ta çok sayıda borulu günlükleme süreci çalışırken ve özellikle HTTPD bir hizmet olarak çalışıyorsa sorunlar baş gösterebilir. Bunun başlıca sebebi masaüstü yığın alanının (heap) dışına taşılmasıdır. Her hizmete ayrılan masüstü yığın alanı, kayıt defterindeki HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\SessionManager\SubSystems\Windows kaydındaki üçüncü değiştirge olan SharedSection değeridir. Bu değeri değiştirirken çok dikkatli olun; bu, Windows kayıt defterini değiştirirken verilen normal uyarılardandır, fakat eğer bu değer çok yüksek olursa masaüstü yığın alanının tükenebileceği dikkate alınmalıdır.

Sanal Konaklar

Bir sunucu çok sayıda sanal konak ile hizmet sunarken bunların günlük kayıtları için çeşitli seçenekler mevcuttur. İlk seçenekte, sanki sunucu tek bir konakla hizmet sunuyormuş gibi günlük kaydı yapılır. Günlükleme yönergelerini <VirtualHost> bölümlerinin dışına, ana sunucu bağlamına yerleştirerek tüm isteklerin aynı erişim ve hata günlüğüne yazılmasını sağlamak olasıdır. Bu teknik, tek tek sanal konaklar için kolayca istatistik toplamaya izin vermez.

Eğer CustomLog veya ErrorLog yönergesi bir <VirtualHost> bölümüne yerleştirilirse bu sanal konağa bütün erişimler veya hatalar belirtilen dosyaya günlüklenecektir. Böyle günlükleme yönergeleri içermeyen sanal konakların günlükleri hala ana sunucunun hata ve erişim günlüklerine yazılmaya devam edecektir. Bu teknik az sayıda sanal konak barındıran sunucular için çok kullanışlıdır. Fakat sanal konak sayısı çok fazlaysa bu teknikle günlük dosyalarını yönetmek çok karmaşık bir hal alabilir. Ayrıca, yetersiz dosya tanıtıcısı sorunlarıyla çok sık karşılaşılabilir.

Erişim günlükleri için çok az bir fedakarlıkla çok iyi bir çözüm vardır. Günlük biçemine sanal konaklarla ilgili bilgi eklemek suretiyle tüm konakların aynı günlük dosyasını kullanmaları olasıdır. Böylece günlük dosyası sonradan her sanal konak için ayrı bir dosya oluşturmak üzere ayrıştırılabilir. Örneğin, bu işlem için şu yönergeler kullanılıyor olsun:

LogFormat "%v %l %u %t \"%r\" %>s %b" ortaksankon
CustomLog logs/access_log ortaksankon

%v belirteci isteği sunan sanal konağın ismini günlüğe yazmak için kullanılır. Daha sonra split-logfile gibi bir program kullanarak, bu dosyadan her sanal konak için ayrı birer dosya elde edilebilir.

Diğer Günlük Dosyaları

İlgili Modüller İlgili Yönergeler
  • mod_logio
  • mod_log_config
  • mod_log_forensic
  • mod_cgi
  • LogFormat
  • BufferedLogs
  • ForensicLog
  • PidFile
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength

Gönderilen ve alınan bayt sayısının günlüklenmesi

mod_logio modülü LogFormat yönergesinde kullanılan biçem belirteçlerine alınan ve gönderilen bayt sayıları için iki belirteç (%I ve %O) ekler.

Adli Günlük

mod_log_forensic modülü istemci isteklerinin kanıt olarak kullanılmak amacıyla günlüklenmesini sağlar. Günlükleme her istek için isteğe hizmet sunmadan önce ve sonra olmak üzere iki defa yapılır. Böylece günlük dosyasında başarılı her istek için iki satır bulunur. Adli günlükleme çok sıkı kurallara tabi olup kişiselleştirilemez. Güvenlik ve hata ayıklama aracı olarak yararlı değildir.

PID Dosyası

Apache httpd başlatıldığında, ana httpd sürecinin kimliği (PID) logs/httpd.pid dosyasına kaydedilir. Bu dosyanın ismi PidFile yönergesi ile değiştirilebilir. Bu süreç kimliği sistem yöneticisi tarafından ana sürece sinyal göndererek artalan sürecini sonlandırmak veya yeniden başlatmak için kullanılır. Windows üzerinde bu işlem için -k komut satırı seçeneği kullanılır. Bu konuda daha ayrıntılı bilgi edinmek için Durdurma ve Yeniden Başlatma belgesine bakınız.

Betik Günlüğü

ScriptLog yönergesi CGI betiklerinin girdi ve çıktılarını kaydetmenizi mümkün kılmak suretiyle hata ayıklamaya yardımcı olur. Bu sadece deneysel amaçla kullanılmalı, asıl sunucuya uygulanmamalıdır. mod_cgi belgesinde daha fazla bilgi bulunabilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


URL’lerin Dosya Sistemi ile Eşleştirilmesi - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

URL’lerin Dosya Sistemi ile Eşleştirilmesi

Bu belgede, bir istekte belirtilen URL’nin sunulacak dosyanın dosya sistemindeki yerini bulmak için Apache HTTP Sunucusu tarafından nasıl kullanıldığı açıklanmaktadır.

İlgili Modüller ve Yönergeler

İlgili Modüller İlgili Yönergeler
  • mod_actions
  • mod_alias
  • mod_autoindex
  • mod_dir
  • mod_imagemap
  • mod_negotiation
  • mod_proxy
  • mod_rewrite
  • mod_speling
  • mod_userdir
  • mod_vhost_alias
  • Alias
  • AliasMatch
  • CheckSpelling
  • DirectoryIndex
  • DocumentRoot
  • ErrorDocument
  • Options
  • ProxyPass
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • Redirect
  • RedirectMatch
  • RewriteCond
  • RewriteRule
  • ScriptAlias
  • ScriptAliasMatch
  • UserDir

DocumentRoot

Yapılan bir isteğe hangi dosyanın sunulacağına karar verirken httpd’nin öntanımlı davranışı istek için URL yolunu (URL’den konak ismi ve port ayrıldıktan sonra kalan kısım) alıp bunu yapılandırma dosyasında DocumentRoot yönergesi ile belirtilen dizinin sonuna eklemektir. Bu nedenle, DocumentRoot altındaki dizinler ve dosyalar sitenin dışardan görünen temel belge ağacını oluştururlar.

Örneğin, DocumentRoot yönergesine /var/http/html atanmış olsun. http://example.com/balıklar/zargana.html şeklindeki bir istek için istemciye /var/http/html/balıklar/zargana.html dosyası sunulur.

Bir dizin istenirse (/ ile biten bir yol belirtilmesi durumu), sunulacak dosya DirectoryIndex yönergesinde belirtilen dosya olacaktır. Örneğin, DocumentRoot yukarıdaki gibi belirtimiş ve siz de şunu belirtmişseniz:

DirectoryIndex index.html index.php

http://www.example.com/fish/ isteği, httpd'nin /var/www/html/fish/index.html dosyasını sunmaya, bu dosya bulunmuyorsa /var/www/html/fish/index.php dosyasını sunmaya çalışmasına sebep olacaktır.

Bu dosyaların ikisi de bulunmuyorsa sonraki adım, mod_autoindex yüklü ve uygun şekilde yapılandırılmışsa bir dizin içeriği dosyası sağlamaya çalışmak olacaktır.

httpd ayrıca, sunucunun birden fazla konak için istek kabul etmesini sağlayan sanal barındırmaya da muktedirdir. Bu durumda her sanal konak için ayrı bir DocumentRoot belirtilebileceği gibi sunulacak içeriğin istekte bulunulan IP adresi veya konak ismine dayanarak devingen olarak saptanmasını sağlayabilen mod_vhost_alias modülüyle gelen yönergeler de kullanılabilir.

DocumentRoot yönergesi yapılandırma dosyanızda ana sunucu için bir tane ve muhtemelen oluşturduğunuz her sanal konak için de birer tanedir.

Belge Kök Dizini Dışındaki Dosyalar

Bazen dosya sisteminde doğrudan DocumentRoot altında bulunmayan dosyalara da erişim izni vermek gerekir. httpd’de bunu sağlamanın çeşitli yolları vardır. Unix sistemlerinde sembolik bağlar sayesinde dosya sisteminin farklı yerlerindeki dosyaları ve dizinleri DocumentRoot altındaymış gibi göstermek mümkündür. Options yönergesine değer olarak FollowSymLinks veya SymLinksIfOwnerMatch atanmadıkça httpd olası güvenlik açıklarına karşı öntanımlı olarak sembolik bağları izlemez.

Bundan başka, dosya sisteminin farklı parçalarını belge kök dizini altında göstermek için Alias yönergesi de kullanılabilir. Örneğin,

Alias "/belgeler" "/var/http"

yapılandırması ile http://example.com/belgeler/dizin/dosya.html URL’si için dosya sistemindeki /var/http/dizin/dosya.html dosyası sunulacaktır. Hedef dizindeki dosyaları birer CGI betiği olarak imlemesi dışında ScriptAlias yönergesi de aynı şekilde çalışır.

Biraz daha fazla esnekliğin gerektiği durumlarda düzenli ifadelere dayalı eşleşmeler sağlamak üzere AliasMatch ve ScriptAliasMatch yönergelerinin gücünden yararlanılabilir. Örneğin,

ScriptAliasMatch "^/~([a-zA-Z0-9]+)/cgi-bin/(.+)" "/home/$1/cgi-bin/$2"

satırı sayesinde http://example.com/~user/cgi-bin/betik.cgi URL’si /home/user/cgi-bin/betik.cgi dosyası ile eşleştirilir ve dosya bir CGI betiği olarak çalıştırılırdı.

Kullanıcı Dizinleri

Geleneksel olarak Unix sistemlerinde belli bir kullanıcının (örn, birisi) ev dizinine ~birisi/ şeklinde atıfta bulunulabilir. mod_userdir modülü bu özelliği site üzerinden kullanıcıların ev dizinlerindeki dosyaları kişisel sayfalar olarak sunmalarını sağlamak üzere kullanır. Örnek:

http://example.com/~birisi/dosya.html

Güvenlik sebebiyle kullanıcıların ev dizinlerine doğrudan HTTP erişimi vermek uygun olmaz. Bu bakımdan, kullanıcının ev dizini altında HTTP erişimi verilecek dosyaların bulunduğu dizini belirtmek için UserDir yönergesi sağlanmıştır. Öntanımlı olan Userdir public_html yapılandırması ile yukarıdaki gibi bir URL kullanıcının ev dizini (/etc/passwd dosyasında belirtilir) /home/birisi/ altında yer alan /home/birisi/public_html/dosya.html dosyası ile eşleşirdi.

Ev dizininin yerinin /etc/passwd dosyasında belirtilmediği sistemlerde kullanılmak üzere Userdir yönergesinin başka kullanım şekilleri de vardır.

Bazı kişiler (genellikle URL üzerinde %7e olarak kodlanması sebebiyle) "~" simgesini biçimsiz bulabilir ve kullanıcı dizinlerini imlemek için başka bir karakter kullanmayı tercih edebilirler. Bu işlevsellik mod_userdir tarafından desteklenmemektedir. Ancak, kullanıcı dizinleri düzgün şekilde yapılandırılmışsa istenen etki AliasMatch yönergesi ile sağlanabilir. Örneğin, http://example.com/sayfalar/birisi/dosya.html URL’si ile /home/birisi/public_html/dosya.html dosyasını eşlemek için AliasMatch yönergesi şöyle kullanılabilirdi:

AliasMatch "^/sayfalar/([a-zA-Z0-9]+)(/(.*))?$" "/home/$1/public_html/$3"

URL Yönlendirme

Yukarıdaki bölümlerde açıklanan yapılandırma yönergeleri httpd’ye içeriği dosya sisteminin belli bir yerinden alıp istemciye göndermesini söyler. Bazen istemciye, istediği içeriğe farklı bir URL ile erişebileceğini ve bu URL için ayrı bir istek yapması gerektiğini bildirmek gerekir. Bu işleme yönlendirme adı verilir ve bu işlevsellik Redirect yönergesi ile sağlanır. Örneğin, DocumentRoot altındaki /foo/ dizininin içeriğinin /bar/ adında yeni bir dizine taşınması halinde istemciye yeni konumun bildirilmesi şöyle sağlanabilirdi:

Redirect permanent "/foo/" "http://example.com/bar/"

Bu atama sayesinde /foo/ ile başlayan URL yolları example.com sunucundaki /bar/ dizini altındaki içeriğe yönlendirilmektedir. Yönlendirmeyi aynı sunucu üzerinde yapmak zorunda değilsiniz, bu yönerge ile başka bir sunucuya da yönlendirme yapabilirsiniz.

httpd ayrıca, yeniden yazma ile ilgili daha karmaşık sorunlara çözüm olarak RedirectMatch diye bir yönerge daha sağlar. Örneğin bir sitenin baş sayfasını diğer isteklerden ayrı olarak farklı bir siteye yönlendirmek için yönergeyi şöyle kullanabilirsiniz:

RedirectMatch permanent "^/$" "http://example.com/ilksayfa.html"

Bundan başka, bir sitedeki tüm sayfalara yapılan istekleri başka bir siteye geçici olarak yönlendirmek için şöyle bir şey yapabilirsiniz:

RedirectMatch temp ".*" "http://mesela.example.com/ilksayfa.html"

Karşı Vekil

httpd ayrıca, uzak sunuculardaki belgelerin yerel sunucunun URL alanına getirilmesini de mümkün kılar. Bu tekniğe HTTP sunucunun belgeleri uzak bir sunucudan alıp istemciye sunmasını sağlayarak bir vekil sunucu gibi davranması nedeniyle ters vekalet adı verilir. Belgelerin istemciye özkaynağın bulunduğu sunucudan geliyormuş gibi değilde doğrudan isteği yaptığı sunucudan geliyormuş gibi sunulması nedeniyle bu işlem normal vekaletten farklıdır.

Aşağıdaki örnekte, istemci /foo/ dizini altından bir belge istemekte, sunucu ise bu belgeyi dahili.example.com üzerindeki /bar/ dizininden alıp istemciye yerel sunucudan geliyormuş gibi sunmaktadır:

ProxyPass "/foo/" "http://dahili.example.com/bar/"
ProxyPassReverse "/foo/" "http://dahili.example.com/bar/"
ProxyPassReverseCookieDomain dahili.example.com harici.example.com
ProxyPassReverseCookiePath "/foo/" "/bar/"

ProxyPass sunucuyu uygun belgeleri alması için yapılandırırken ProxyPassReverse yönergesi dahili.example.com sunucusundan kaynaklanan yönlendirmeleri yeniden yazar, böylece bunların yerel sunucudaki yerleri belirlenmiş olur. Benzer şekilde, ProxyPassReverseCookieDomain ve ProxyPassReverseCookiePath yönergeleri de arka sunucu tarafından atanan çerezleri yeniden yazar.

Yalnız, belgelerin içindeki hiperbağların yeniden yazılmayacağına dikkat ediniz. Dolayısıyla, belge içinde dahili.example.com’u ismiyle hedef alan mutlak hiperbağlar varsa bunlar istemci tarafından vekil sunucudan değil doğrudan dahili.example.com’dan istenecektir. Bir sayfanın içindeki bu bağları (ve diğer içeriği) mod_substitute modülü kullanılarak istemciye sunuluyormuşçasına değiştirebilirsiniz.

Substitute "s/dahili\.example\.com/harici.example.com/i"

HTML ve XHTML’de hiperbağları daha bilgece yeniden yazabilen mod_proxy_html modülü de kullanılabilir. Yeniden yazılması gereken URL eşlemlerini oluşturmanızı sağlar, böylece karmaşık vekil senaryoları oluşturulabilir.

Yeniden Yazma Motoru

Daha güçlü ikameler gerektiğinde mod_rewrite modülü tarafından sağlanan yeniden yazma motoru işe yarayabilir. Bu modüldeki yönergeler sunulacak içeriğin yerine karar vermek için kaynak IP adresi, tarayıcı türü gibi isteğe özgü özellikleri kullanırlar. mod_rewrite modülü buna ek olarak isteğin nasıl ele alınacağına karar vermek için harici yazılımları ve veritabanlarını kullanabilir. Yeniden yazma motoru yukarıda değinilen üç eşleşme türünü de uygulayabilecek yetenektedir: Dahili yönlendirmeler (rumuzlar), harici yönlendirmeler ve vekalet. mod_rewrite modülü tarafından sağlanan yeteneklerin ayrıntılı açıklamaları ve bunların kullanım örnekleri ayrıntılı olarak mod_rewrite belgelerinde bulunmaktadır.

Dosya orada yok

Kaçınılmaz olarak, dosya sisteminde mevcut olmayan dosyalar için de istek yapılacaktır. Bunun çeşitli sebepleri olabilir. Bazı durumlarda bu, belgelerin yerlerininin değiştirilmesinin bir sonucu olabilir. Bu durumda yapılacak en iyi şey, istemciyi belgeyi yeni yerinden istemesi için bilgilendirmek amacıyla URL yönlendirmesi kullanmaktır. Bu şekilde, içeriğin yeri değişse bile eski yer imlerinin ve hiperbağların çalışmaya devam edeceklerinden emin olabilirsiniz.

"Dosya orada yok" ("File Not Found") hatalarının diğer bir bildik sebebi de URL’lerin hiperbağlarda veya doğrudan tarayıcıda kasıtlı ya da kasıtsız, yanlış yazılmasıdır. Bu tür sorunlarda yardımcı olması için httpd mod_speling (sic) adında bir modülle gelir. Bu modül etkin kılındığında htpd, "Dosya orada yok" ("File Not Found") hatalarının önünü kesip başka bir yerde benzer isimde bir dosya var mı diye bakar. Böyle bir dosya varsa, mod_speling istemciye dosyanın doğru yerini bildiren bir HTTP yönlendirmesi yollar. Benzer çok sayıda dosya varsa bunlar istemciye bir liste halinde sunulur.

mod_speling modülünün en yararlı özelliklerinden biri de dosya isimlerini harf büyüklüğüne duyarsız olarak arayabilmesidir. Dosya isimlerinde harf büyüklüğünün önemli olduğu Unix benzeri sistemler hakkında bilgisi olmayan kullanıcılara sahip sistemlerin kullanıcılarına bu büyük yarar sağlar. Fakat modülün URL düzeltmekten başka şeyler için de kullanılması, istemcilerden gelen neredeyse her isteğin URL yönlendirmesine konu olmasına sebep olarak sunucunun yükünü arttırabilir.

mod_dir modülü sanal URI'leri, onları sunan gerçek kaynağa eşlemekte kullanılan FallbackResource yönergesini içerir. Bir 'ön denetleyici' gerçeklerken mod_rewrite modülünün kullanılmasını sağlamak için çok kullanışlıdır.

Yerinde bulunmayan içeriğin bulunması çabalarının tümü Apache’nin 404 (Dosya orada yok) HTTP durum kodlu bir hata sayfası döndürmesine yol açar. Bu sayfanın içeriği ErrorDocument yönergesi ile denetlenebilir ve Hata Yanıtlarının Kişiselleştirilmesi bölümünde anlatıldığı gibi oldukça esnek bir şekilde kişiselleştirilebilir.

Diğer URL Eşleme Modülleri

URL eşlemede kullanılabilecek diğer modüller:

  • mod_actions - Bir isteği, özkaynağın MIME türüne veya istek yöntemine bakarak bir CGI betiğine eşler.
  • mod_dir - URL'yi sonlandıran bölü çizgisini index.html bir dosyaya eşler.
  • mod_imagemap - Bir isteği, bir HTML belge içindeki bir resme yapılan kullanıcı tıklamalarına dayanarak bir URL'ye eşler.
  • mod_negotiation - Dil veya içerik sıkıştırması gibi kullanıcı tercihlerine dayanarak uygun bir belgeyi seçer.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Devingen Paylaşımlı Nesne Desteği - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Devingen Paylaşımlı Nesne Desteği

Apache HTTP Sunucusu modüler bir program olup, yönetici sadece bir grup modül seçerek sunucuya işlevsellik ekleyebilir. Modüller, Devingen Paylaşımlı Nesneler (DSO - Dynamic Shared Object) halinde httpd programından ayrı olarak derlenir. DSO modülleri sunucunun derlenmesi sırasında derlenebileceği gibi ayrı olarak derlenip daha sonra Apache Eklenti Aracı (Apache Extension Tool) apxs programı kullanılarak da sunucuya eklenebilir.

Bu belgede DSO modüllerinin kullanımının yanında teorisine de değinilecektir.

Gerçeklenim

İlgili Modüller İlgili Yönergeler
  • mod_so
  • LoadModule

Apache httpd modüllerini yüklemek için DSO desteği, Apache httpd çekirdeğine durağan olarak ilintilenerek derlenmiş olan mod_so adında bir modül tarafından sağlanır. core modülünden başka, bir DSO modülü olamayan tek modül mod_so modülüdür. Apache ile dağıtılan hemen hemen tüm diğer Apache modülleri bir DSO modülüne yerleştirilebilir. Derlenmiş modüller mod_filanca.so biçeminde birer DSO ismi alırlar ve her biri istenirse httpd.conf dosyasında mod_so modülünün LoadModule yönergesiyle belirtilerek sunucu başlatılırken veya yeniden başlatılırken sunucuya yüklenebilir.

Kurulum belgesinde açıklandığı gibi, her DSO modülü configure programının --enable-mods-static seçeneği ile devredışı bırakılabilir.

Apache httpd modülleri için (özellikle üçüncü parti modüller için) DSO dosyası üretimini kolaylaştırmak amacıyla apxs (APache eXtenSion) adında yeni bir destek programı kullanılmaktadır. Bu program Apache httpd modüllerini Apache httpd kaynak ağacından ayrı olarak derlemek için kullanılabilir. Fikir basittir: Apache HTTP Sunucusu derlenirken DSO dosyalarını derlemek için platforma bağımlı derleyici ve ilintileyici seçenekleri apxs programının içine konur ve make install ile kurulum sırasında Apache httpd C başlık dosyaları da kurulur. Böylece kullanıcı Apache httpd dağıtımının kaynak ağacına ihtiyaç duymadan ve platforma bağımlı derleyici ve ilintileyici seçeneklerini bilmek zorunda kalmadan istediği Apache httpd modülünü apxs programını kullanarak derleyebilir.

Kullanım Özeti

Apache HTTP Sunucusu 2.x’in DSO özelliklerine bir giriş olarak burada kısaca bir bilgi vermekle yetinilecektir:

  1. Kaynak dosyası mod_filanca.c dosyasında dağıtılan bir özgün Apache htpd modülünü mod_filanca.so isminde bir DSO modülü olarak derlemek ve kurmak için şöyle yapılır:

    $ ./configure --prefix=/kurulum/yeri --enable-filanca
    $ make install

  2. Apache HTTP Sunucusunu tüm modüller etkin olarak derleyebilirsiniz. Fakat sunucunun başlatılması sırasında sadece temel modüller yüklenir. Daha sonra httpd.conf içindeki LoadModule yönergelerini etkin veya etkisiz hale getirerek yüklenecek modülleri değiştirebilirsiniz.

    $ ./configure --enable-mods-shared=all
    $ make install

  3. Bazı modüller sadece geliştiriciler içindir ve bunlar tüm modüllerin derlenmesini (all) seçseniz bile derlenmeyecektir. Geliştirici modülleri dehil tüm modülleri derlemek isterseniz reallyall kullanınız. Ek olarak, derlenmiş modüller için kullanılan LoadModule yönergelerinin tamamını --enable-load-all-modules derleme seçeneği ile etkin kılabilirsiniz.

    $ ./configure --enable-mods-shared=reallyall --enable-load-all-modules
    $ make install

  4. Kaynak dosyası mod_filanca.c dosyasında dağıtılan bir üçüncü parti Apache httpd modülü mod_filanca.so isminde bir DSO modülü olarak Apache httpd kaynak ağacının dışında apxs kullanarak derlemek ve kurmak için şöyle yapılır:

    $ cd /bir/kurulum/yeri
    $ apxs -c mod_filanca.c
    $ apxs -aci filanca mod_filanca.la

Tüm durumlarda derlenen paylaşımlı modülü Apache httpd’nin etkin kılabilmesi için httpd.conf dosyasında o modül için bir LoadModule yönergesi bulunmalıdır.

Ayrıntılı bilgi için apxs belgelerine bakınız.

Artalan Bilgisi

Günümüzün Unix türevlerinde var olan bir mekanizma sayesinde çalıştırılabilir bir programın adres uzayına çalışma anında yüklenmek veya ilintilenmek üzere Devingen Paylaşımlı Nesneler (DSO - Dynamic Shared Object) adı verilen, özel bir biçem kullanarak kodlanmış program parçaları oluşturulabilir.

Bu yükleme normalde iki yolla yapılabilir: Ya çalıştırılabilir programın başlatılması sırasında yüklenen ld.so adlı bir sistem programınının devingen olarak yüklenmesi ile ya da çalıştırılabilir programın içinden Unix yükleyicisine programsal sistem arayüzü sağlayan dlopen()/dlsym() sistem çağrılarının elle yapılması suretiyle.

İlk yöntemde kullanılan DSO’lara genelde paylaşımlı kütüphaneler veya DSO kütüphaneleri adı verilir ve bunların dosyaları libfilanca.so veya libfilanca.so.1.2 biçiminde isimlendirilir. Belli bir sistem dizininde (normalde /usr/lib) bulunurlar ve derleme sırasında ilintileyici komutuna -lfilanca şeklinde belirtilerek çalıştırılabilir programla ilintilenirler. Doğrudan çalıştırılabilir koda eklenen bu kodlar Unix yükleyicisinin programın başlatılması sırasında kütüphaneyi /usr/lib altında libfilanca.so adıyla bulabilmesini sağlar. Kütüphanelerin aranacağı yerler ya -R gibi bir ilintileyici seçeneği ile koda eklenir ya da arama yolları LD_LIBRARY_PATH ortam değişkeni aracılığıyla yapılandırılır. Böylece çalıştırılabilir programda henüz çözümlenmemiş simgeler DSO içinde bulunarak çözümlenebilir.

Çalıştırılabilir program içindeki simgelere normalde DSO içinden atıfta bulunulmaz (genel kod kütüphanesinin başka programlarca da kullanılması nedeniyle). Bu bakımdan DSO tarafında böyle bir çözümleme yapılmaz. Çalıştırılabilir program da DSO’daki simgeleri kendisi çözümlemeye uğraşmaz, bu işlemlerden tamamen Unix yükleyicisi (ld.so) sorumludur. (Aslında, ld.so’yu çağıracak kod, her çalıştırılabilir programın içine ilintilenmiş (durağan değil) başlatma kodunun bir parçasıdır.) Programlar tarafından ortaklaşa kullanılan kütüphanelerin devingen olarak yüklenmesinin sebebi basittir: Kütüphane kodu libc.so gibi bir sistem kütüphanesine bir kere kaydedilip disk alanından yer kazanılmış olur.

İkinci yöntemde kullanılan DSO’lara yine paylaşımlı kütüphaneler veya DSO kütüphaneleri adı verilir fakat bunların dosyaları geçerli kabule göre filanca.so gibi isimlendirilse de genelde keyfi olarak seçilen bir dosya uzantısı kullanılarak isimlendirilirler. Bu dosyalar genellikle programa özel bir dizinde dururlar ve bu dosyaları kullanacak olan çalıştırılabilir programla aralarında özdevimli olarak bağ kurulmamıştır. Bunun yerine, çalıştırılabilir program DSO’yu çalışma anında dlopen() sayesinde kendi adres uzayına ekler. Çalıştırılabilir program için DSO’daki simgeler bu sırada çözümlenmez. Özdevimli olarak devreye giren Unix yükleyicisi, (varsa) artakalan simgeleri, çalıştırılabilir ihraç edilen simge kümelerini (ve özellikle her yerde hazır ve nazır libc.so içindeki tüm simgeleri) kullanarak çözümler. Bu yolla DSO, çalıştırılabilir programın simge kümesi bilgilerini sanki kendisine baştan durağan olarak ilintilenmiş gibi ulaşabilir.

Son olarak, DSO’nun programlama arayüzünün getirilerinden yararlanmak amacıyla çalıştırılabilir program, daha sonra dağıtım tabloları vb. yerlerde kullanmak üzere dlsym() üzerinden DSO’daki belli simgeleri çözümlemek zorundadır. Başka bir deyişle: Çalıştırılabilir program ihtiyaç duyduğu her simgeyi kullanmak için kendisi çözümleme yapmak zorundadır. Böyle bir mekanizmanın getirisi, programın isteğe bağlı parçalarının gerekli olana kadar yüklenmemesidir (böylece daha az bellek alanı kullanılır). Gerektiği zaman programın işlevselliğini arttırmak amacıyla bu parçalar devingen olarak programa yüklenebilir.

DSO mekanizmasının bu basit gibi görünen işleyişinde zorluk içeren bir adım şudur (başkaları da olabilir): Bir programın işlevselliğini genişletmek için DSO kullanılırken (ikinci yöntem) çalıştırılabilir programdan DSO için simgelerin çözümlenmesi. Zorluğun sebebi, "tersine çözümleme" yapılmasıdır; çalıştırılabilir programın simge kümesindeki DSO simgeleri kütüphane tasarımına aykırı bir şekilde çözümlenir ve bu uygulama tüm platformlarda hazır olarak desteklenmediği gibi standartlaşmış da değildir. Geçer uygulamada çalıştırılabilir programın evrensel simgeleri çoğunlukla yeniden dışa verilmez ve bu bakımdan bir DSO içinde kullanılmaları uygun değildir. Esas sorun, çalıştırılabilir bir programın işlevselliğini çalışma anında genişletmek için DSO kullanımı sırasında ilintileyicinin tüm evrensel simgeleri dışa vermesini zorlamanın bir yolunu bulmaktır.

Paylaşımlı kütüphane yaklaşımı bu bakımdan türünün tek örneğidir, çünkü DSO mekanizması özellikle bunun için tasarlanmıştır, dolayısıyla işletim sisteminin sağladığı hemen hemen tüm kütüphaneler için kullanılabilir.

Getiriler ve Götürüler

Yukarıda bahsedilen DSO’ya dayalı özelliklerin getirileri şunlardır:

  • Sunucu paketi çalışma anında daha esnektir çünkü, sunucuyu oluşturan parçalar derleme sırasında configure seçenekleriyle birleştirilmek yerine httpd.conf içinde LoadModule yönergeleri sayesinde çalışma anında birleştirilebilmektedir. Bu yolla, örneğin tek bir Apache kurulumuyla birbirinden farklı yapılandırmalara sahip çok sayıda sunucu çalıştırmak mümkündür. (standart veya SSL sürümü; basitleştirilmiş veya devingen sürümü [mod_perl, PHP3], vs.)
  • Sunucu paketi kurulumdan sonra bile üçüncü parti modüllerle kolayca genişletilebilir. Bu özellikle, bir Apache temel paketinin yanında PHP, mod_perl, mod_security gibi ek paketler oluşturan paket dağıtıcılarına büyük yarar sağlar.
  • Yeni Apache httpd modülleri için daha kolay prototip geliştirilebilir: Modül kaynak kodunu DSO/apxs çifti sayesinde Apache httpd kaynak ağacının dışında derleyip modülün yeni bir sürümünü bir apxs -i komutunun ardından apachectl restart yaparak çalışan bir Apache HTTP Sunucusunda denemek daha kolay hale getirilmiştir.

DSO kullanımının götürüleri ise şunlardır:

  • İlk yüklemede %20 yavaşlama: Unix yükleyicisi simgeleri çözümlemek zorunda olduğundan sunucu ilk başlatılırken yaklaşık %20 daha yavaş faaliyete geçer.
  • Çalışma sırasında % 5 yavaşlama: Konumdan bağımsız kodun (PIC - Position Independent Code) göreli adresleme için karmaşık oyunlara girmesi ve bunun mutlak adresleme kadar hızlı olmaması nedeniyle sunucu bazı platformlarda çalışma anında yaklaşık %5 daha yavaş çalışabilir.
  • DSO'nun tüm modüller için uygun olmaması: DSO modülleri bazı platformlarda diğer DSO temelli kütüphanelerle ilintilenemediğinden (ld -lfilanca) DSO mekanizmasını tüm modül türleri için kullanamazsınız (örneğin a.out temelli platformlar bu işlevselliği ELF temelli platformlar kadar iyi sağlamaz). Başka bir deyişle, DSO dosyaları olarak derlenmiş modüllerin kullanabileceği simgeler ya Apache httpd temel kodunda vardır ya Apache httpd temel kodunun kullandığı C kütüphanesinde (libc) ve diğer durağan ve devingen kütüphanelerde vardır ya da konumdan bağımsız kodu içeren durağan kütüphane arşivlerinde (libfilanca.a) vardır. Diğer modülleri kullanmak için tek şansınız ya Apache httpd çekirdeğinin modüle bir atıf içermesini sağlamak ya da modül kodunu dlopen() vasıtasıyla yüklemektir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


İçerik Uzlaşımı - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

İçerik Uzlaşımı

Apache HTTPD, içerik uzlaşımını HTTP/1.1 belirtiminde bahsedildiği şekliyle destekler. Bir özkaynağın en iyi gösterimini, tarayıcının sağladığı karakter kodlaması, karakter kümesi, dil, ortam türü gibi kullanıcı tercihlerine bağlı olarak seçebilir. Ayrıca, tarayıcının kullanıcı tercihlerini tam yansıtamadığı durumlarda istekleri daha akıllıca ele alabilmeyi sağlayacak bir takım özelliklere de sahiptir.

İçerik uzlaşımı öntanımlı olarak derlenen mod_negotiation modülü tarafından sağlanır.

İçerik Uzlaşımı Hakkında

Bir özkaynağın bir çok farklı gösterimi olabilir. Örneğin, bir belgenin farklı ortam türleri ve/veya farklı diller için gösterimleri olabilir. En uygun seçimi yapmanın tek yolu kullanıcıya bir liste verip seçmesini istemektir. Bununla birlikte sunucunun bu seçimi kendiliğinden yapması da mümkündür. Tarayıcılar isteğin bir parçası olarak kullanıcı tercihlerini de gönderdiğinden bu istendiği gibi çalışır. Örneğin bir tarayıcı, kullanıcısınının mümkünse Fransızca içerik tercih ettiğini yoksa İngilizce içeriğe de razı olabileceğini belirtebilirdi. Tarayıcılar bu tercihleri başlıkta belirtirler. Tarayıcı sadece Türkçe içerik istendiğini şöyle belirtebilirdi:

Accept-Language: tr

Bu tercihin yerine getirilebilmesininin sadece, desteklenen diller arasında bu dilin varlığına ve istenen belgenin bu dilde bir gösteriminin bulunmasına bağlı oluşuna dikkat ediniz.

Daha karmaşık bir istek örneği olarak, tarayıcının Fransızca ve İngilizce içerik kabul etmeye ayarlandığını fakat Fransızcayı tercih ettiğini ve çeşitli ortam türlerini kabul etmekle birlikte salt metin ve diğer metin türlerinden ziyade HTML tercih ettiğini, ayrıca, diğer ortam türleri üzerinde GIF veya JPEG tercih ettiğini fakat başka çare yoksa her ortam türüne de izin verdiğini belirtiyor olsun:

Accept-Language: fr; q=1.0, en; q=0.5
Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1

httpd, HTTP/1.1 belirtiminde tanımlanan şekliyle ‘sunucu yönetiminde’ içerik uzlaşımını destekler. Accept, Accept-Language, Accept-Charset ve Accept-Encoding istek başlıklarını tamamen destekler. httpd ayrıca, RFC 2295 ve RFC 2296’da tanımlanan bir deneysel uzlaşım olarak ‘şeffaf’ içerik uzlaşımını da destekler. Fakat ‘özellik uzlaşımını’ bu RFC’lerde tanımlandığı gibi desteklemez.

Bir özkaynak bir URI (RFC 2396) tarafından betimlenen kavramsal bir öğedir. Apache gibi bir HTTP sunucusu, ortam türü, karakter kümesi, kodlama ve saire ile tanımlanmış bir bayt dizisi şeklindeki her gösterimiyle, özkaynaklara kendi isim alanları dahilinde erişim sağlar. Her özkaynağın aynı anda bir veya daha fazla gösterimi mevcut olabileceği gibi hiç mevcut olmayabilir de. Eğer çok sayıda gösterim mevcutsa, bu özkaynağın uzlaşılabilir olduğundan ve her gösteriminin bir çeşitlilik oluşturduğundan bunun da uzlaşımın boyutlarından kaynaklandığından bahsedilebilir.

httpd’de İçerik Uzlaşımı

Bir özkaynak üzerinde uzlaşılırken gösterim çeşitlerinin her biri hakkında sunucuya bilgi verilmesi gerekir. Bu iki yolla yapılabilir:

  • Ya gösterim çeşitlerini içeren dosyaların isimleriyle eşleşmeyi sağlayan bir tür eşlemi kullanılır (bir *.var dosyası gibi).
  • Ya da sunucu örtük bir dosya ismi kalıbı eşleşmesinin ardından sonuçlar arasından seçim yapar; buna ‘Çoklu Görünüm’ araması adı verilir.

Bir türeşlem dosyası kullanmak

Bir türeşlem dosyası, type-map eylemcisi ile ilişkili bir belgedir (ya da eski httpd yapılandırmaları ile geriye uyumluluk için, application/x-type-map MIME türünde bir belgedir). Bu özelliği kullanmak için, yapılandırmada bir tür eşleyici olarak her dosya ismi uzantısı için bir type-map eylemcisi tanımlamalısınız. Bu, sunucu yapılandırma dosyasında en iyi şöyle yapılabilir:

AddHandler type-map .var

Türeşlem dosyaları kendilerini tanımlayan özkaynak ile aynı isimde olmalı ve isim bir .var uzantısı içermelidir. Aşağıdaki örneklerde özkaynak ismi foo olduğundan türeşlem dosyasının ismi foo.var'dır.

Bu dosya her gösterim çeşidi için bir girdi içermelidir; bu girdiler ardarda belirtilen HTTP biçem başlık satırlarından oluşur. Farklı gösterimlerin girdileri bir boş satırla diğerlerinden ayrılır. Aynı girdi içinde boş satır kullanılamaz. Bir eşlem dosyasını bir birleşik öğenin tamamı için bir girdi ile başlatmak adet olmuştur (ise de, bu gerekli değildir, hele yoksayılacaksa hiç gerekli değildir). Eşlem dosyası için aşağıda bir örnek verilmiştir.

Bu dosyadaki URI'ler türeşlem dosyasının yerine görelidir. Dolayısıyla, bu dosyaların aynı dizinde bulunması beklenirse de bu gerekli değildir. Aynı sunucuda bulunan tüm dosyalar için türeşlem dosyasındaki gibi mutlak veya göreli URI'ler belirtebilirsiniz.

URI: misal

URI: misal.en.html
Content-type: text/html
Content-language: en

URI: misal.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de

Ayrıca, MultiViews etkin olsa bile bir türeşlem dosyasının dosya ismi uzantılarının taranmasına göre öncelik alacağına dikkat ediniz. Eğer gösterimler bu örnekteki resim dosyasında olduğu gibi farklı kaynak üstünlüklerine sahipseler, ortam türünün qs parametresi kullanılarak kaynak üstünlükleri belirtilebilir:

URI: misal

URI: misal.jpeg
Content-type: image/jpeg; qs=0.8

URI: misal.gif
Content-type: image/gif; qs=0.5

URI: misal.txt
Content-type: text/plain; qs=0.01

qs değerleri 0.000-1.000 değer aralığı içinde belirtilebilir. 0.000 qs değerine sahip gösterimin asla seçilmeyeceğine dikkat ediniz. Bir qs değeri belirtilmeyen gösterimlerin kaynak üstünlüğü 1.000 kabul edilir. qs parametresinin belirttiği değer istemcinin yeteneklerinden bağımsız olarak olası gösterimler arasında göreli bir üstünlük ifade eder. Örneğin bir fotoğraf sözkonusu olduğunda bir JPEG dosyasının kaynak üstünlüğü bir ASCII çiziminkinden yüksek olacaktır. Diğer taraftan özgün resim bir ASCII çizim olduğu takdirde, ASCII çizim, bir JPEG gösterimine göre öncelikli olacaktır. Bu nedenle qs değeri özkaynağın doğasına bakarak belirlenir.

Tanınan başlıkların tam listesini mod_negotiation modülünün belgesinde bulabilirsiniz.

Çoklu Görünümler

MultiViews, httpd.conf dosyasındaki veya (AllowOverride yönergesinin değerine bağlı olarak) .htaccess dosyalarındaki <Directory>, <Location> veya <Files> bölümleri içinde Options yönergeleri ile belirtilebilen, dizine özgü bir seçenektir. Yalnız, dikkatli olun, Options All yaparak MultiViews seçeneğini etkin kılamazsınız; seçeneği ismiyle açıkça belirtmelisiniz.

MultiViews şöyle etki eder: Sunucudan, MultiViews seçeneğinin etkin olduğu /bir/dizin dizininden filanca dosyası için bir istekte bulunulmuşsa fakat dizinde bu dosya yoksa, sunucu dizin içeriğini filanca.* dosyaları için tarar ve bu dosyalar için istemcinin ismiyle talep ettiği ortam türlerini ve kodlamaları kullanarak bir türeşlem dosyası uydurup bu gösterimler arasından istemcinin gereksinimlerine en uygun gösterimi seçer.

MultiViews ayrıca, sunucunun bir dizin içeriğini listelemeye çalıştığı durumda DirectoryIndex yönergesi ile belirtilen dosya için de bir arama tertipleyebilir. Eğer yapılandırma dosyalarında

DirectoryIndex index

şeklinde bir atama varsa ve dizinde index.html ve index.html3 dosyaları varsa sunucu bunlar arasından hakem sıfatıyla bir seçim yapacaktır; ama bu ikisi yerine dizinde sadece index.cgi mevcutsa sunucu sadece bu dosyayı çalıştıracaktır.

Okunan dizinde bulunan dosyalar arasında mod_mime tarafından tanınan karakter kümesi, içerik türü, dil ve kodlama başlıklarına uygun gösterim uzantılarından birine sahip bir dosya yoksa sonuç MultiViewsMatch yönergesiyle yapılan tanıma bağlı olur. Bu yönerge hangi diğer dosya uzantılarının, eylemcilerin veya süzgeçlerin çok gösterimli uzlaşımla ilintileneceğini belirler.

Uzlaşım Yöntemleri

httpd’nin, bir türeşlem dosyası veya dizin içindeki bir dosya sayesinde belli bir özkaynağın gösterim çeşitlerinin bir listesini elde ettikten sonra ‘en uygun’ gösterime karar vermek için kullanabileceği iki yöntem vardır. httpd’nin içerik uzlaşım özelliklerinin kullanımı sırasında uzlaşımın nasıl yerine getirileceği ile ilgili ayrıntıları bilmek aslında gerekli değildir. Bununla birlikte belgenin kalanında bu konu açıklanmaya çalışılmıştır.

İki uzlaşım yöntemi vardır:

  1. Normal durumda sunucu yönetiminde httpd uzlaşım algoritması kullanılır. Bu algoritma aşağıda ayrıntılı olarak açıklanmıştır. Bu algoritma kullanıldığı zaman, httpd, en iyi sonuca ulaşmak için bazen belli boyutların üstünlük katsayılarıyla ‘oynar’. httpd’nin bu katsayılarla oynama işini nasıl yaptığı aşağıda daha ayrıntılı açıklanmıştır.
  2. İstemci bu işlem için özellikle RFC 2295’te tanımlanan mekanizmanın kullanılmasını isterse şeffaf içerik uzlaşımı kullanılır. Bu uzlaşım yöntemi, en uygun gösterimin seçilmesi konusunda tarayıcıya tam denetim imkanı verir; dolayısıyla sonuç tarayıcının bu işlem için kullandığı algoritmanın başarısına bağlıdır. Şeffaf uzlaşım sürecinin bir parçası olarak, tarayıcı, RFC 2296’da tanımlanan ‘gösterim çeşidini uzaktan seçme algoritması’nın çalıştırılmasını httpd’den isteyebilir.

Uzlaşımın Boyutları

Boyut | Açıklama
Ortam Türü | Tarayıcı ortam türü tercihlerini Accept başlık alanı ile belirtir. Her öğenin kendine özgü bir üstünlük katsayısı olabilir. Gösterimin açıklaması da ayrıca bir kaynak üstünlüğüne (qs parametresi) sahip olabilir.
Dil | Tarayıcı dil tercihlerini Accept-Language başlık alanı ile belirtir. Her öğenin kendine özgü bir üstünlük katsayısı olabilir. Gösterimler bir kaç dilde olabileceği gibi hiç bir dille ilişkilendirimemiş de olabilir.
Kodlama | Tarayıcı kodlama tercihlerini Accept-Encoding başlık alanı ile belirtir. Her öğenin kendine özgü bir üstünlük katsayısı olabilir.
Karakter Kümesi | Tarayıcı karakter kümesi tercihlerini Accept-Charset başlık alanı ile belirtir. Her öğenin kendine özgü bir üstünlük katsayısı olabilir. Gösterim çeşitleri karakter kümesini ortam türünün bir parametresi olarak belirtebilirler.

httpd Uzlaşım Algoritması

httpd, tarayıcıya döndürülecek en uygun gösterim çeşidini (varsa) seçmek için aşağıdaki algoritmayı kullanabilir. Bu algoritma pek de yapılandırılabilir değildir. Şöyle çalışır:

  1. Önce her uzlaşım boyutu için ilgili Accept* başlık alanına bakılıp her gösterim çeşidine bir üstünlük katsayısı atanır. Eğer boyutlardan bazıları için ilgili Accept* başlığı uygulanabilir değilse bu boyut elenir ve sonuçta hiçbir gösterim çeşidi kalmasza 4. adıma atlanır.
  2. ‘En uygun’ gösterim çeşidi bir eleme süreciyle seçilir. Bu süreç sırasında aşağıdaki sınamalar sırayla uygulanır. Sınamalardan geçemeyen bir gösterim çeşidi elenir. Sınamaların bir aşamasında tek bir gösterim çeşidi kalırsa bu en uygun eşleşme olarak seçilmiş olur ve 3. adıma atlanır. Eğer birden fazla gösterim çeşidi kalırsa sonraki sınamaya geçilir.
    1. Accept başlığındaki üstünlük katsayısı ile gösterimin ortam türünde belirtilen kaynak üstünlüğünün çarpımı en büyük olan gösterim çeşidi seçilir.
    2. En yüksek dil üstünlük katsayısına sahip gösterim çeşidi seçilir.
    3. En uygun dil eşleşmesine sahip gösterim çeşidini seçmek için önce varsa Accept-Language başlığındaki dil sıralamasına bakılır, aksi takdirde LanguagePriority yönergesi ile atanmışsa oradaki dil sıralamasına bakılır.
    4. En yüksek ‘seviyeden’ ortam parametresine (text/html ortam türü sürümünü belirtmekte kullanılır) sahip gösterim çeşitleri seçilir.
    5. Accept-Charset başlık satırında belirtilene bakarak en uygun karakter kümesine sahip gösterim çeşitleri seçilir. Alenen dışlanmadıkça ISO-8859-1 kabul edilebilir karakter kümesidir. text/* ortam türüne sahip gösterim çeşitlerinden belli bir karakter kümesi ile ilişkilendirilmemiş olanların karakter kümesinin ISO-8859-1 olduğu varsayılır.
    6. ISO-8859-1 karakter kümesi ile ilişkilendirilmemiş gösterim çeşitleri seçilir. Böyle hiçbir gösterim yoksa bütün gösterimler seçilir.
    7. En uygun kodlamaya sahip gösterim çeşitleri seçilir. Tarayıcı tarafından kabul edilebilir kodlamaya sahip gösterim çeşitleri varsa bunlar seçilir. Yoksa kodlanmış ve kodlanmamış gösterim çeşitleri karışık olarak mevcutsa sadece kodlanmamış olanlar seçilir. Eğer bütün gösterim çeşitlerinin sadece kodlanmış ya da sadece kodlanmamış gösterimleri mevcutsa hepsi seçilir.
    8. En küçük içerik uzunluğuna sahip gösterim çeşitleri seçilir.
    9. Kalan gösterim çeşitlerinin ilki seçilir. Bu ilk, ya türeşlem dosyasında listelenen ilk çeşittir ya da gösterimler bir dizinden okunuyorsa ASCII kod sıralamasına göre ilk sıradaki dosya ismine sahip gösterimdir.
  3. Algoritma, artık seçilmiş en uygun gösterim çeşidine sahipse bu artık yanıt olarak döndürülebilir. HTTP yanıt başlığı Vary’ye uzlaşım boyutları atanır (tarayıcı ve arabellekler özkaynağı kaydederken bu bilgiyi kullanırlar) ve algoritma sonlandırılır.
  4. Buraya gelinmişse hiçbir gösterim seçilmemiş demektir (hiçbiri tarayıcı tarafından kabul edilebilir bulunmadığından dolayı). Gövdesinde mevcut gösterim çeşitlerini listeleyen bir HTML belgesi 406 durum koduyla döndürülür (406: ‘kabul edilebilir bir gösterim yok’). Ayrıca HTTP Vary başlığında gösterim çeşitliliğinin boyutları belirtilir.

Üstünlük Değerleriyle Oynamak

httpd bazen yukarıdaki httpd uzlaşım algoritmasının kesin sonucunun beklenenden farklı olması için üstünlük değerleriyle oynar. Bunu tam ve doğru bilgi göndermeyen tarayıcılar için algoritmadan en iyi sonucu elde etmek amacıyla yapar. Bazen günümüzün en tanınmış tarayıcıları bile çoğu durumda yanlış bir seçimle sonuçlanmayacaksa Accept başlık bilgilerini göndermemektedir. Eğer tarayıcı eksiksiz ve doğru bilgi gönderirse httpd bu değerlerle oynamayacaktır.

Ortam Türleri ve Dosyaismi Kalıpları

Accept: istek başlığı ortam türü tercihlerini yansıtır. Ayrıca, * bir dizge ile eşleşmek üzere "image/*" veya "*/*" gibi ortam türü kalıpları da içerebilir. Dolayısıyla şöyle bir istek,

Accept: image/*, */*

diğer türler gibi "image/" ile başlayan ortam türlerini kabul edilebilir kılacaktır. Bazı tarayıcılar ortam türlerini örtük olarak elde etmek amacıyla hep bu tür kalıplar gönderirler. Örnek:

Accept: text/html, text/plain, image/gif, image/jpeg, */*

Bunun amacı, açıkça listelenmiş türlerin tercih edildiğini, fakat farklı gösterimler varsa onların da kabul edilebileceğini belirtmektir. Üstünlük değerlerini doğrudan kullanarak tarayıcılar gerçekte ne istediklerini şuna benzer şekilde belirtebilirler:

Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01

Açıkça belirtilen türler için üstünlük katsayısı belirtilmemiştir, dolayısıyla üstünlük katsayılarının 1.0 (en yüksek) olduğu varsayılmaktadır. */* kalıbı 0.01 gibi çok daha düşük bir öncelik belirtmektedir. Bu bakımdan, ancak, açıkça belirtilen türlerden hiçbirinin bulunmaması halinde diğer türler eşleşecektir.

Eğer Accept: başlığı hiçbir q katsayısı içermiyorsa ve başlıkta "*/*" belirtilmişse, httpd istenen davranışı taklit etmek için bu kalıba 0.01 katsayısını atar. Keza "type/*" kalıbına da 0.02 katsayısını atar (yani, */* kalıbına göre tercihli olur). Eğer Accept: alanındaki her ortam türü bir q katsayısı içeriyorsa bu özel değerler uygulanmaz. Dolayısıyla gerekli bilgiyi açıkça bildiren tarayıcılardan gelen istekler umulduğu gibi işlem görecektir.

Dil Uzlaşımında İstisnalar

httpd 2.0’dan itibaren, uzlaşım algoritmasına, bir eşleşme bulmak konusunda algoritma başarılı olamadığı takdirde hoş bir son çareye izin vermek için bazı istisnalar eklenmiştir.

İstemci sunucudan bir sayfa istediğinde, sunucu, tarayıcı tarafından gönderilen Accept-language başlığıyla eşleşen tek bir sayfa bulamadığı takdirde istemciye ya “Kabul edilebilir bir gösterim çeşidi yok” ya da “Çok sayıda seçim belirtilmiş” yanıtını döndürür. Bu hata iletilerinden kaçınmak için bu gibi durumlarda httpd Accept-language başlığını yoksaymaya ayarlanabilir. Böylece istemcinin isteğine tam olarak uymasa da bir belge sağlanır. Bu hata iletilerinin birini veya her ikisini de geçersiz kılmak için ForceLanguagePriority yönergesi kullanılabilir ve sunucunun kararını LanguagePriority yönergesine dayanarak vermesi sağlanabilir.

Sunucu ayrıca, tam bir eşleşme bulunmadığı zaman lehçelerle de eşleşme arayabilir. Örneğin, bir istemci Britanya İngilizcesi (en-GB) ile yazılmış belgeler için istekte bulunursa, sunucu normalde HTTP/1.1 standardına göre bir belgenin basitçe en olarak imlenmesine izin vermez. (Bir okuyucu Britanya İngilizcesini anlıyor ama genel İngilizceyi anlamıyor diye Accept-Language başlığında en değil de en-GB’yi belirtmesinin hemen hemen daima bir yapılandırma hatasına yol açacağına dikkat ediniz. Maalesef, mevcut istemcilerin çoğu öntanımlı yapılandırmalarında buna benzer şeyler yapmaktadır.) Bununla birlikte, başka bir dille eşleşme mümkün değilse ve sunucu “Kabul edilebilir bir gösterim çeşidi yok” hatasını döndürmeye hazırsa veya LanguagePriority son çaresine ayarlanmışsa alt küme belirtimini yok sayacak ve en belge isteklerine en-GB belgelerle yanıt verecektir. httpd, lehçenin üyesi olduğu anadili, istemcinin kabul edilebilir diller listesine örtük olarak düşük bir üstünlük değeri ile ekler. Yalnız şuna dikkat edin, eğer istemci tercihini "en-GB; q=0.9, fr; q=0.8" olarak belirtirse ve sunucuda sadece "en" ve "fr" belgeleri varsa sunucu "fr" belge ile yanıt verecektir. HTTP/1.1 belirtimi ile uyumluluğu sağlamak ve düzgün yapılandırılmış istemcilerle gerektiği gibi çalışabilmek için bu gereklidir.

Gelişmiş tekniklerin (çerezler, özel URL yolları gibi) desteklenmesi sırasında, kullanıcının tercih ettiği dili saptamak için httpd 2.0.47 sürümünden beri mod_negotiation modülü prefer-language ortam değişkenini tanımaktadır. Değişken mevcutsa ve uygun bir dil yaftası içeriyorsa mod_negotiation uygun gösterimi seçmeyi deneyecektir. Böyle bir gösterim çeşidi mevcut değilse normal uzlaşım işlemi uygulanacaktır.

Örnek

SetEnvIf Cookie "language=(.+)" prefer-language=$1
Header append Vary cookie

Şeffaf İçerik Uzlaşımının Genişletilmesi

httpd, şeffaf içerik uzlaşımı protokolünü (RFC 2295) şöyle genişletir: Sadece içerik kodlamasına özgü olmak üzere gösterim çeşidi listelerinde gösterim çeşitlerini imlemek için yeni bir {encoding ..} elemanı kullanılır. RVSA/1.0 algoritmasının (RFC 2296) gerçeklenimi, listedeki kodlanmış gösterim çeşitlerini tanımak ve onları Accept-Encoding başlık alanıyla ilgili olarak kabul edilebilir kodlamalara aday gösterim çeşitleri olarak kullanmak üzere genişletilmiştir. RVSA/1.0 gerçeklenimi, en uygun gösterim çeşidi seçiminin öncesinde hesaplanmış üstünlük katsayısını virgülden sonra beş haneye yuvarlamaz.

Hiperbağlar ve İsimlendirme Uzlaşımları

Eğer dil uzlaşımı kullanıyorsanız ve birden fazla dosya ismi uzantısına sahip dosyalarınız varsa uzantıların sıralamasının normalde uygunsuz düştüğü farklı isimlendirme yaklaşımlarında bulunabilirsiniz (ayrıntılar için mod_mime belgesine bakınız).

Bir MIME türü uzantısına sahip bir dosyanın (html gibi), kodlanmış bir gösterimi (gz gibi) mevcut olabilir. Bu dosyanın ayrıca farklı dillerdeki gösterimleri için de bir uzantısı (en gibi) olabilir.

Örnekler:

  • misal.en.html
  • misal.html.en
  • misal.en.html.gz

Hiperbağ olarak geçerli ve geçersiz bazı dosya ismi örnekleri:

Dosya ismi | Geçerli Hiperbağ | Geçersiz Hiperbağ
misal.html.en | misal misal.html | -
misal.en.html | misal | misal.html
misal.html.en.gz | misal misal.html | misal.gz misal.html.gz
misal.en.html.gz | misal | misal.html misal.html.gz misal.gz
misal.gz.html.en | misal misal.gz misal.gz.html | misal.html
misal.html.gz.en | misal misal.html misal.html.gz | misal.gz

Yukarıdaki tabloya bakarak hiperbağlarda bir dosya ismini uzantısız olarak (misal gibi) kullanmanın daima mümkün olduğunu farkedeceksiniz. Böylece bir belgenin asıl türünü gizleyebilir ve sonradan bir hiperbağ değişikliği yapmaksızın örneğin html’den shtml veya cgi’ye geçebilirsiniz.

Hiperbağlarda MIME türlerini (misal.html gibi) kullanmaya devam etmek istiyorsanız dil uzantısı MIME türü uzantısının sağında kalmalıdır (misal.html.en gibi).

Arabellekler Hakkında

Bir arabellek, bir gösterimi istek URL’si ile ilişkilendirerek saklar. Böylece, sonradan aynı URL için bir istek yapıldığında kaydettiği gösterimi kullanabilir. Fakat özkaynak sunucuyla uzlaşılan türdeyse arabelleğe ilk istenen çeşit saklanmış olacağından isteğe yanlış gösterimle yanıt verilmiş olacaktır. Bunun olmaması için httpd, normal olarak içerik uzlaşımının sonucu olarak döndürülen tüm yanıtları HTTP/1.0 istemciler tarafından arabelleklenemez olarak imler. httpd ayrıca, uzlaşımlı yanıtların arabelleklenmesini mümkün kılan HTTP/1.1 protokolünü de destekler.

HTTP/1.0 uyumlu istemcilerden (bir tarayıcı veya arabellek) gelen istekler için, uzlaşıma konu yanıtların arabelleklenmesini mümkün kılmak üzere CacheNegotiatedDocs yönergesi kullanılabilir. Bu yönerge argümansızdır ve sunucu genelinde veya sanal konakların yapılandırılmasında kullanılabilir. Bunun HTTP/1.1 istemcilerinden gelen isteklere bir etkisi yoktur.

HTTP/1.1 istemciler için, httpd, yanıtın uzlaşım boyutlarını göstermek üzere bir Vary HTTP yanıt başlığı gönderir. Arabellekler bu bilgiyi sonraki istekleri yerel kopyadan sunarken kullanabilirler. Bir arabelleğin uzlaşım boyutlarına bakmaksızın yerel kopyasını kullanmaya teşvik etmek için force-no-vary ortam değişkenini etkin kılabilirsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Hata Yanıtlarının Kişiselleştirilmesi - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Hata Yanıtlarının Kişiselleştirilmesi

Apache HTTP Sunucusu 4xx veya 5xx HTTP durum kodları ile ilgili olaylarda soysal hata yanıtları üretse de bu yanıtlar site kullanıcılarına aşırı sade, bilgi vermez ve hatta korkutucu gelebilir. Daha dostça yazılmış, İngilizce değil de kendi dilinizde ve belki sayfalarınızın yerleşimine uygun daha hoş satırlarda özel hata yanıtları üretmek isteyebilirsiniz.

Kişiselleştirilmiş hata yanıtları, bir hata durumuna göre tasarlanmış herhangi bir HTTP durum kodu (yani 4xx ve 5xx kodlarından biri) için tanımlanabilir.

Ek olarak bir değer kümesi de sağlanmıştır. Böylece hata belgeleri, Sunucu taraflı İçerik Yerleştirme kullanılarak bu değişkenlerin değerlerine göre özelleştirilebilir. İsterseniz bunun yerine bir CGI programı veya devingen bir eylemci (PHP, mod_perl, vs.) kullanarak da bu değişkenlerin değerlerine göre hata sayfalarınızı üretebilirsiniz.

Yapılandırma

Kişiselleştirilmiş hata belgeleri ErrorDocument yönergesi kullanılarak yapılandırılabilir. Bu yönerge küresel bağlamda olabileceği gibi sanal konak ve dizin bağlamlarında da kullanılabilir. AllowOverride yönergesine FileInfo atanarak .htaccess dosyalarında da kullanılabilir.

ErrorDocument 500 "Pardon, galiba bizim betik hata verdi."
ErrorDocument 500 /cgi-bin/hata-kurtarma
ErrorDocument 500 http://error.example.com/server_error.html
ErrorDocument 404 /ozuru_kabahatinden_buyuk/yok.html
ErrorDocument 401 /Uyeler/NASIL_uye_olunur.html

ErrorDocument yönergesinin sözdizimi:

ErrorDocument <3-rakamlı-kod> <eylem>

eylem şunlardan biri olabilir:

  1. Yönlendirmenin yapılacağı dahili adres (eylem bir "/" ile başlıyorsa).
  2. Yönlendirmenin yapılacağı harici adres (eylem geçerli bir URL ise).
  3. Gösterilecek metin (yukardakilerin hiçbiri yoksa). Birden fazla sözcük içeriyorsa tırnak (") içine alınmalıdır.

Yerel bir adrese yönlendirme yapılırken ek ortam değişkenleri de atanarak yanıt daha da özelleştirilebilir. Bunlar harici URL'lere gönderilmez.

Kullanılabilen Değişkenler

Hata durumunu açıklayacak veya hata günlüğüne daha açıkça kaydedilebilecek bazı bilgilerin aktarılması koşuluyla, başka bir adrese yönlendirme kullanışlı olabilir

Hata yönlendirmesi yapılırken bunu sağlamak için ek ortam değişkenleri tanımlanır. Bu değişkenlerin isimleri, özgün istekle sağlanan başlık isimlerinin önüne 'REDIRECT_' dizgesi getirilerek üretilir. Böylece özgün istek bağlamından hata belgesi üretilebilir.

Örneğin, aşağıdaki gibi, daha yararlı olacak ek ortam değişkenleri alabilirsiniz.

REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png
REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8
REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=client.example.com
REDIRECT_SERVER_NAME=www.example.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/2.2.15
REDIRECT_URL=/cgi-bin/buggy.pl

REDIRECT_ ortam değişkenleri, yönlendirme öncesi varolan ortam değişkenlerinden üretilir. Bunlar önlerine REDIRECT_ getirilerek yeniden isimlendirilir. Örneğin, HTTP_USER_AGENT değişkeni REDIRECT_HTTP_USER_AGENT haline gelir.

REDIRECT_URL, REDIRECT_STATUS ve REDIRECT_QUERY_STRING mutlaka atanır. Diğer başlıklarla ilgili olanlar ise hata durumu öncesinde mevcut oldukları takdirde üretilirler.

Eğer ErrorDocument hedefi bir harici yönlendirme ise bunların hiçbiri üretilmez (sunucunun bulunduğu konağı hedeflese bile http: ile başlayan herşey harici yönlendirme sayılır).

Özel Hata Yanıtları

Hata yanıtınızı üretmek için sunucu taraflı içerik yerleştirme, bir CGI betiği veya başka bir eylemciyi devingen eylemci olarak kullanıyorsanız, bu yanıtı özelleştirmek için bu kullanıma özel üretilmiş ortam değişkenlerini kullanmak isteyebilirsiniz.

ErrorDocument yönergesi bir CGI betiğine bir yerel yönlendirme belirtiyorsa, hatanın kaynağı hakkında istemciye bilgi vermek amacıyla betiğin çıktısında bir "Status:" başlık alanına yer verilmelidir. Örneğin, bir Perl betiği şunları içerebilirdi:

...
print  "Content-type: text/html\n";
printf "Status: %s durumu saptandı.\n", $ENV{"REDIRECT_STATUS"};
...

Eğer betik, 404 Not Found gibi, belli bir hata durumunu ele almaya adanmışsa duruma özel kod ve hata metni kullanılabilir.

Eğer yanıt, (istemci taraflı yönlendirme yapılırken) bir Location: başlığı da içeriyorsa betiğin çıktıya uygun bir Status: başlığı (302 Found) eklemesinin gerekli oluşuna dikkat ediniz. Aksi takdirde, Location: başlığı etkisiz olabilir.

Çok Dilli Özel Hata Belgeleri

Apache HTTP Sunucusunun kurulumunda, 16 dile çevrilmiş özel hata iletileri belgeleri içeren bir dizin bulunmaktadır. Ayrıca, conf/extra yaplandırma dizininde bu özelliği etkin kılmak için yapılandırmaya dahil edilebilecek bir yapılandırma dosyası vardır.

Sunucu yapılandırma dosyanızda şöyle satırlar görebilirsiniz:

# Multi-language error messages
#Include conf/extra/httpd-multilang-errordoc.conf

Bu Include satırını açıklama olmaktan çıkarırsanız bu özelliği etkinleştirmiş olursunuz. Böylece, istemcinin tarayıcısında belirtilmiş dil tercihine uygun dil uzlaşımlı hata iletileri sağlanır.

Ek olarak, bu belgeler çeşitli REDIRECT_ değişkenleri içerir. Böylece, son kullanıcıya neler olduğu ve şimdi ne yapması beklendiği hakkında ek bilgiler sağlanabilir.

Bu belgeleri istediğiniz kadar özelleştirebilir, kullanıcıya siteniz hakkında ve orada bulabilecekleri şeylere dair faydalı bilgiler de sağlayabilirsiniz.

Bu özelliği kullanmak için mod_include ve mod_negotiation etkin kılınmalıdır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Adresleri ve Portları Dinleme - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Adresleri ve Portları Dinleme

Apache HTTPD sunucusunun belli adresleri ve portları dinlemek üzere yapılandırılması.

Ayrıca bakınız:

  • Sanal Konaklar
  • DNS Konuları

Genel Bakış

İlgili Modüller İlgili Yönergeler
  • core
  • mpm_common
  • <VirtualHost>
  • Listen

httpd başlatıldığında yerel makinedeki bazı adres ve portları kendine bağlar ve gelecek istekleri bekler. Öntanımlı olarak makine üzerindeki tüm adresleri dinler. Bununla birlikte, belli portları veya sadece seçilmiş bazı adresleri ya da her ikisini de dinlemesi için bunun belirtilmesi gerekebilir. Bu çoğunlukla, httpd’nin farklı IP adreslerine, konak isimlerine ve portlarına nasıl yanıt vereceğinin belirlendiği sanal konak özelliği ile birlikte yürür.

Listen yönergesi sunucuya gelen istekleri sadece belli port(lar)dan veya belli adres ve port birleşimlerinden kabul etmesini söyler. Listen yönergesinde sadece port numarası belirtilmişse sunucu tüm arabirimlerin belirtilen portunu dinleyecektir. Portla birlikte bir IP adresi de belirtilmişse sunucu belirtilen portu ve arabirimi dinleyecektir. Çok sayıda adres ve portu dinlemek için çok sayıda Listen yönergesi kullanılabilir. Sunucu böyle bir durumda belirtilen bütün adres ve portlardan gelen isteklere yanıt verecektir.

Örneğin, sunucunun hem 80 portundan hem de 8000 portundan gelen bağlantıları kabul etmesini sağlamak için,

Listen 80
Listen 8000

yapılandırmasını kullanabilirsiniz. Sunucunun 80 portuna gelen bağlantıları bir arabirimden 8000 portuna gelenleri ise başka bir arabirimden kabul etmesini sağlamak için ise,

Listen 192.0.2.1:80
Listen 192.0.2.5:8000

yapılandırmasını kullanabilirsiniz. IPv6 adresleri aşağıdaki örnekteki gibi köşeli ayraçlar içine alınarak belirtilmelidir:

Listen [2001:db8::a00:20ff:fea7:ccea]:80

Bir Listen yönergesinin aynısının tekrarı sunucunun başlatılmasını engelleyen ölümcül bir hatayla sonuçlanacaktır.

(48)Address already in use: make_sock: could not bind to address [::]:80

Sorun giderme ile ilgili ipuçları için wiki belgesine bakınız.

IPv6 Adreslerin Durumu

IPv6’yı gerçekleyen platformların sayısı giderek artmaktadır. Bu platformların çoğunda APR, httpd’nin IPv6 soketleri ayırmasını mümkün kılarak IPv6’yı desteklemekte ve IPv6 üzerinden gönderilmiş istekleri elde etmektedir.

httpd yöneticilerinin kafasını karıştırıran tek şey IPv6 soketlerin hem IPv4 hem de IPv6 bağlantılarını kabul edip etmeyeceğidir. IPv4 bağlantılarını kabul eden IPv6 soketleri IPv4 eşlemli IPv6 adresleri kullanırlar. Bu çoğu sistemde öntanımlı olarak böyleyken, FreeBSD, NetBSD ve OpenBSD’de sistem geneline uygulanan kurallar gereğince öntanımlı olarak buna izin verilmez; bu sistemlerde özel bir configure parametresi ile httpd’nin davranışı değiştirilebilir.

Diğer taraftan, Linux ve Tru64 gibi bazı platformlarda hem IPv4 hem de IPv6 adresleri kabul etmenin tek yolu eşlemli adresler kullanmaktır. httpd’nin IPv4 ve IPv6 adresleri, IPv4 eşlemli IPv6 adreslerin kullanımını gerektiren en az sayıda soketle kabul etmesini istiyorsanız, configure betiğine --enable-v4-mapped seçeneğini belirtiniz.

--enable-v4-mapped seçeneği, FreeBSD, NetBSD ve OpenBSD hariç tüm platformlarda öntanımlıdır. Muhtemelen siz de httpd’nin böyle derlenmesini isterdiniz.

Platformunuzun ve APR’nin neyi desteklediğine bakmaksızın httpd’nin sadece IPv4 adresleri kabul etmesini istiyorsanız, tüm Listen yönergelerinde örnekteki gibi IPv4 adresleri belirtiniz:

Listen 0.0.0.0:80
Listen 192.0.2.1:80

Platformunuz IPv4 ve IPv6 adresleri ayrı soketlerden kabul ediyorsa ve httpd’nin de buna uygun davranmasını (yani IPv4 eşlemli IPv6 adreslerin iptalini) istiyorsanız configure betiğine --disable-v4-mapped seçeneğini belirtiniz. Bu seçenek FreeBSD, NetBSD ve OpenBSD’de öntanımlıdır.

Protokolü Listen ile Belirtme

Listen yönergesinin isteğe bağlı ikinci değiştirgesi protokol çoğu yapılandırmada gerekli olmaz. Belirtilmediği takdirde, https için 443, http için ise diğer bütün portlar öntanımlıdır. Protokol, isteğin hangi modül tarafından işleneceğini ve AcceptFilter yönergesi ile uygulanacak protokole özgü en iyilemeleri belirlemekte kullanılır.

Sadece standartdışı bir port kullanmak isterseniz protokolü belirtmeniz gerekir. Örneğin, birhttps sitesini port 8443 üzerinde çalıştırmak isterseniz:

Listen 192.170.2.1:8443 https

Sanal Konaklarla Nasıl Çalışır?

Listen yönergesi sanal konaklar için gerçeklenmemiştir; sadece ana sunucuya hangi adresleri ve portları dinleyeceğini söyler. Hiç <VirtualHost> yönergesi kullanılmamışsa sunucu kabul edilen tüm isteklere aynı şekilde davranacaktır. Eğer bir veya daha fazla adres ve port için farklı bir davranış belirtmek istiyorsanız <VirtualHost> kullanabilirsiniz. Bir sanal konağı gerçeklemek için önce sunucunun sanal konak için kullanacağı adres ve portu dinleyeceğini belirtmek gerekir. Bundan sonra bu sanal konağın davranışını ayarlamak üzere belirtilen adres ve port için bir <VirtualHost> bölümü oluşturulmalıdır. Yalnız dikkat edin, eğer <VirtualHost> için belirtilen adres ve port sunucu tarafından dinlenmiyorsa ona erişemezsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Çok Süreçlilik Modülleri (MPM’ler) - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Çok Süreçlilik Modülleri (MPM’ler)

Bu belgede Çok Süreçlilik Modülü denince ne anlaşıldığı ve bunların Apache HTTP Sunucusu tarafından nasıl kullanıldıkları açıklanmıştır.

Giriş

Apache HTTP Sunucusu çok çeşitli platformlar üstünde farklı ortamlarda çalışabilen güçlü ve esnek bir HTTP sunucusu olarak tasarlanmıştır. Farklı platformlar ve farklı ortamlar çoğunlukla farklı özellikler veya aynı özelliğin en yüksek verimlilikle gerçeklenmesi için farklı yöntemler gerektirir. Apache httpd, geniş ortam çeşitliliğini daima modüler tasarımı sayesinde uzlaştırmıştır. Bu tasarım, site yöneticilerine, sunucularında bulunmasını istedikleri özellikleri derleme sırasında veya çalışma anında gerekli modülleri yüklemek suretiyle seçebilme imkanı verir.

Apache HTTP Sunucusu 2.0, bu modüler tasarımı sunucunun en temel işlevlerine kadar indirmiştir. Sunucu, Çok Süreçlilik Modülleri adı verilen ve makine üzerindeki ağ portlarının bağlanmasından, isteklerin kabul edilmesinden ve bu istekleri yanıtlayacak çocuklara dağıtmaktan sorumlu olan modüllerin seçimine imkan verecek bir yapılanma ile gelir.

Sunucunun modüler tasarımının bu seviyede genişletilmesi iki önemli yarar sağlar:

  • Apache httpd geniş çeşitlilikteki işletim sistemlerini daha temiz ve daha verimli bir şekilde destekleyebilmektedir. Özellikle, mpm_winnt modülü, Apache httpd 1.3’te kullanılan POSIX katmanının yerine işletim sistemine özgü özellikleri kullanabildiğinden, Apache HTTP Sunucusunun Windows sürümü artık çok daha verimli bir duruma gelmiştir. Aynı fayda özelleştirilmiş MPM’lerle diğer işletim sistemlerine de sağlanmıştır.
  • Sunucu, belli bir sitenin ihtiyaçlarına uygun olarak daha iyi kişiselleştirilebilmektedir. Örneğin, eski yazılım ile uyumluluk ve kararlılığa önem veren siteler prefork modülünü kullanabilirken, daha geniş ölçeklenebilirlik gerektiren siteler worker veya event gibi evreli MPM modüllerinden birini seçebilmektedir.

Kullanıcı açısından MPM’lerin diğer Apache httpd modüllerinden görünüşte bir farkı yoktur. Asıl fark sunucuya yüklenebilecek azami MPM modülü sayısının bir ve yalnız bir olarak sınırlanmış olmasıdır. Mevcut MPM modülleri modül dizini sayfasında listelenmiştir.

Öntanımlı MPM’ler

Aşağıdaki tabloda çeşitli işletim sistemlerinde öntanımlı olan MPM’ler listelenmiştir. Derleme sırasında başka bir seçim yapmadığınız takdirde bu işletim sistemlerinde bu MPM’ler seçilmiş olacaktır.

Netware | mpm_netware
OS/2 | mpmt_os2
Unix | Platformun yapabildiklerine bağlı olarak, prefork, worker veya event
Windows | mpm_winnt

'Unix' burada Unix benzeri işletim sistemleri anlamında kullanılmıştır (örn, Linux, BSD, Solaris, Mac OS X, vb.

Unix durumunda, hangi MPM'nin kurulacağı kararı şu 2 soruya verilecek yanıta bağlıdır:

1. Sistem evreleri destekliyor mu?

2. Sistem evreleri "thread-safe polling" anlamında destekliyor mu (özellikle kqueue ve epoll işlevlerini)?

Her iki soruya da verilen yanıt 'evet' ise, öntanımlı MPM'niz event modülüdür.

Birincinin yanıtı 'evet' ikincinin 'hayır' ise öntanımlı MPM'niz worker modülüdür.

Yanıtların her ikisi de 'hayır' ise öntanımlı MPM'niz prefork modülüdür.

Uygulamada, günümüzdeki işletim sistemlerinin tümü bu iki özelliği desteklediğinden öntanımlı MPM'niz hemen hemen daima event modülü olacaktır.

Bir MPM'i bir duruk modül olarak derlemek

MPM'ler tüm platformlarda duruk (static) modüller olarak derlenebilir. Derleme sırasında tek bir modül seçilir ve sunucu ile ilintilenir. MPM değiştirilmek istenirse sunucunun yeniden derlenmesi gerekir.

Öntanımlı MPM seçimin değiştirmek için configure betiğinin --with-mpm=AD seçeneği kullanılır. Buradaki AD istenen MPM'in ismidir.

Sunucu bir kere derlendi mi, hangi MPM'in seçilmiş olduğunu ./httpd -l komutuyla öğrenebilirsiniz. Bu komut, içerilen MPM dahil, sunucu içinde derlenmiş bütüm modülleri listeler.

Bir MPM'i bir DSO modülü olarak derlemek

Unix ve benzeri platformlarda, MPM'ler DSO modülleri olarak derlenebilir ve diğer DSO modülleri gibi sunucuya devingen olarak yüklenebilir. DSO modülü olarak derlenen MPM'ler, sunucunun yeniden derlenmesini gerektirmeden LoadModule yönergesi güncellenerek değiştirilebilir.

LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

LoadModule yönergesini birden fazla MPM için kullanmak sunucunun başlatılması sırasında aşağıdaki hatanın oluşmasına sebep olur.

AH00534: httpd: Configuration error: More than one MPM loaded.

Bu özellik configure betiğinin --enable-mpms-shared seçeneği ile etkinleştirilebilir. all değeri belirtilerek platform için kullanılabilen tüm modüller kurulur. İstenirse, değer olarak bir MPM listesi de belirtilebilir.

Özdevinimli olarak seçilerek veya configure betiğine --with-mpm seçeneğiyle belirtilerek seçilen öntanımlı MPM üretilen sunucu yapılandırma dosyasıyla yüklenir. Farklı bir MPM seçmek için MPM'i LoadModule yönergesinde belirtin.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache’de Ortam Değişkenleri - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache’de Ortam Değişkenleri

Apache HTTP Sunucusunu etkileyen ortam değişkenleri iki çeşittir.

İlki, işletim sisteminin denetimindeki ortam değişkenleridir. Bu değişkenlere değer atama işlemi sunucu başlatılmadan önce yapılır. Bunlar yapılandırma dosyalarının içinde kullanılabilir. Ayrıca, istenirse PassEnv yönergesi kullanılarak bunlar CGI betiklerine ve SSI sayfalarına da aktarılabilir.

İkincisi ise, Apache HTTP Sunucusunun kendi ortam değişkenleridir. Bu değişkenlerde saklanan bilgi erişim denetimi, günlük kaydı gibi çeşitli işlemleri denetlemekte kullanılabilir. Değişkenler ayrıca, CGI betikleri gibi harici uygulamalarla iletişim mekanizması olarak da kullanılabilir. Bu belgede bu değişkenler üzerindeki işlemlere ve kullanım şekillerine değinilmiştir.

Bu değişkenlere ortam değişkenleri dense de işletim sisteminin ortam değişkenleri gibi değillerdir. Bunlar sadece Apache ortamında geçerli değişkenler olup işletim sisteminin bu değişkenlerden haberi olmaz. Sadece CGI betikleri ve SSI sayfaları gibi harici uygulamalar tarafından üretilen ortam değişkenleri sistem ortamının değişkenleri haline gelirler. İşletim sistemi ortamına çalışmakta olan sunucudan müdahale etmek isterseniz işletim sisteminizin kabuğu tarafından sağlanan standart ortam müdahale mekanizmalarını kullanmalısınız.

Ortam Değişkenlerinin Atanması

İlgili Modüller İlgili Yönergeler
  • mod_cache
  • mod_env
  • mod_rewrite
  • mod_setenvif
  • mod_unique_id
  • BrowserMatch
  • BrowserMatchNoCase
  • PassEnv
  • RewriteRule
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • UnsetEnv

Temel Ortamda Değişiklik

Apache ortamında bir ortam değişkenine müdahale etmenin en temel yolu hiçbir koşula tabi olmayan SetEnv yönergesini kullanmaktır. Bu değişkenleri Apache başlatılırken sistem ortam değişkenleri haline getirmek için PassEnv yönergesi kullanılabilir.

İsteğe Bağlı Şartlı Atamalar

Esnekliği arttırmak için, mod_setenvif modülü ile isteğin özelliklerine uygun olarak her isteğe özel değişkenler atayabilmek mümkün kılınmıştır. Örneğin, bir değişken sadece isteği yapan tarayıcıya özgü bir değerle veya sadece belli bir başlık alanınına bağlı olarak atanabilir. Daha da esnek bir mekanizma, ortam değişkeni atamak için [E=...] seçeneğinin kullanıldığı mod_rewrite modülünün RewriteRule yönergesi ile sağlanmıştır.

Eşsiz Betimleyiciler

Son olarak, mod_unique_id UNIQUE_ID ortam değişkenine her istek için o isteğin çok özel koşullar altında tüm diğer istekler arasında eşsizliğini garanti edecek bir değer atar.

Standart CGI Değişkenleri

Apache yapılandırmasıyla atanan ve kabuğa aktarılan ortam değişkenlerinden başka CGI Belirtiminin gerektirdiği istekler hakkında temel bilgileri içeren ortam değişkenlerinin CGI betikleri ve SSI sayfalarınca atanabilmesi sağlanmıştır.

Bazı Yetersizlikler

  • Standart CGI değişkenlerini ortam değişkenlerine müdahale yönergelerini kullanarak değiştirmek veya geçersiz kılmak mümkün değildir.
  • CGI betiklerini çalıştırmak için suexec kullanıldığında ortam, CGI betikleri çalıştırılmadan önce güvenilir değişkenler kalacak şekilde temizlenir. Güvenilir değişken listesi suexec.c içinde derleme sırasında tanımlanır.
  • Taşınabilirlik adına, ortam değişkenlerinin isimleri sadece harfler, rakamlar ve alt çizgi imlerini içerebilir. Bunlara ek olarak ismin ilk karakteri bir rakam olmamalıdır. Değişkenler CGI betiklerine ve SSI sayfalarına aktarılırken bu sınırlamalara uygun olmayan karakterlerin yerlerine alt çizgi imleri konur.
  • Bir özel durum, CGI betiklerine ve benzerlerine ortam değişkenleri üzerinden aktarılan HTTP başlıklarıdır (aşağıya bakın). Bunlar büyük harfe dönüştürülür ve sadece tireler altçizgilere dönüştürülür. Eğer HTTP başlığı geçersiz karakter içeriyorsa başlığın tamamı yoksayılır. Böyle bir durumda ne yapılacağı öğrenmek için aşağıya bakın.
  • İsteklerin işleme konması sırasında SetEnv yönergesi geç çalıştırılır, yani SetEnvIf ve RewriteCond gibi yönergeler SetEnv ile atanan değişken değerlerini görmezler.
  • mod_autoindex ile dizin listesi oluşturulması veya bir DirectoryIndex için yol aranması gibi bir dahili alt istek için sunucu yol araması yaparken isteklere özgü ortam değişkenleri alt istekler tarafından miras alınMAZ. Buna ek olarak, mod_setenvif modülünün devreye girdiği API fazlarından dolayı yapılan alt isteklerde SetEnvIf yönergeleri ayrı ayrı değerlendirilMEZ.

Ortam Değişkenlerinin Kullanımı

İlgili Modüller İlgili Yönergeler
  • mod_authz_host
  • mod_cgi
  • mod_ext_filter
  • mod_headers
  • mod_include
  • mod_log_config
  • mod_rewrite
  • Require
  • CustomLog
  • Deny
  • ExtFilterDefine
  • Header
  • LogFormat
  • RewriteCond
  • RewriteRule

CGI Betikleri

Ortam değişkenlerinin başlıca amaçlarından biri CGI betikleriyle iletişim kurmaktır. Yukarıda bahsedildiği gibi CGI betiklerine aktarılan ortam Apache yapılandırmasında atanan değişkenlere ek olarak istek hakkında standart temel bilgileri de içerir. Bu konuda ayrıntılı bilgi edinmek için CGI Öğreticisine bakabilirsiniz.

SSI Sayfaları

Sunucu tarafında mod_include modülünün INCLUDES süzgeci ile yorumlanan SSI sayfalarında ortam değişkenleri echo elemanı ile basılabilir ve sayfayı isteğin özelliklerine uygun olarak oluşturmak için ortam değişkenleri akış denetim elemanları içinde kullanılabilir. Apache ayrıca, yukarıda bahsedildiği gibi standart CGI ortam değişkenli SSI sayfalarını da sağlayabilmektedir. Daha ayrıntılı bilgi edinmek için SSI Öğreticisine bakabilirsiniz.

Erişim Denetimi

allow from env= ve deny from env= yönergeleri sayesinde ortam değişkenlerine dayalı olarak sunucuya erişim denetim altında tutulabilir. Bunlar SetEnvIf yönergesi ile birlikte kullanılmak suretiyle sunucuya erişim isteğin özelliklerine bağlı olarak daha esnek bir tarzda denetlenebilir. Örneğin, belli bir tarayıcının sunucuya erişimi bu yönergelerle engellenebilir.

Şartlı Günlük Kaydı

Ortam değişkenleri LogFormat yönergesinin %e seçeneği kullanılarak erişim günlüğüne kaydedilebilir. Bundan başka, CustomLog yönergesi sayesinde isteklerin günlüğe kaydedilip kaydedilmeyeceğine ortam değişkenlerine dayalı olarak karar verilmesi sağlanabilir. Bunlar SetEnvIf yönergesi ile birlikte kullanılmak suretiyle günlük kayıtları isteğin özelliklerine bağlı olarak daha esnek bir tarzda denetlenebilir. Örneğin, gif uzantılı dosyalar için yapılan isteklerin günlüğe kaydedilmemesi veya sadece alt ağınızın dışından gelen isteklerin günlüğe kaydedilmesini isteyebilirsiniz.

Şartlı Yanıt Başlıkları

Header yönergesi belli bir yanıt başlığının istemciye gönderilip gönderilmeyeceğine belli bir ortam değişkeninin varlığına bakarak karar vermek için kullanılabilir. Böylece örneğin, belli bir başlığın istemciye gönderilmesine istemciden belli bir başlığın alınıp alınmadığına bağlı olarak karar verilebilir.

Harici Süzgeçlerin Etkinleştirilmesi

mod_ext_filter tarafından yapılandırılan harici süzgeçler ExtFilterDefine yönergesinin disableenv= ve enableenv= seçenekleri kullanılarak bir ortam değişkenine bağlı olarak etkinleştirilebilir.

URL Kurgulaması

RewriteCond yönergesinin SınamaDizgesi olarak kullanılan %{ENV:değişken} biçemi mod_rewrite yeniden yazma motorunun ortam değişkenlerine bağlı kararlar almasını mümkün kılar. Yalnız şuna dikkat ediniz: mod_rewrite’ta ENV: öneki kullanılmadan belirtilen değişkenler ortam değişkenleri değillerdir. Onlar mod_rewrite’a özgü diğer modüllerden erişilemeyen özel değişkenlerdir.

Özel Amaçlı Ortam Değişkenleri

Birlikte çalışabilirlik sorunları Apache’nin belli istemcilerle veri alışverişi sırasında davranışını değiştirmesini gerektirebilir. Genellikle SetEnv ve PassEnv yönergelerinden başka BrowserMatch gibi yönergelerle ortam değişkenleri atanarak bunu sağlayan mekanizmaların olabildiğince esnek davranabilmesi sağlanabilir.

downgrade-1.0

İstek, daha yüksek bir HTTP protokolüyle yapılmış olsa bile HTTP/1.0 isteği olarak ele alınır.

force-gzip

DEFLATE süzgeci etkinse tarayıcının tercih ettiği kodlama koşulsuz olarak yoksayılarak sıkıştırılmış çıktı gönderilir.

force-no-vary

İstemciye gönderilmeden önce yanıttan Vary alanının çıkarılmasına sebep olur. Bazı istemciler bu alanı gerektiği gibi yorumlayamazlar, bu değişken atanarak bu sorunla karşılaşılmamaya çalışılır. Bu değişkenin atanması ayrıca force-response-1.0 değişkeninin de atanmasına sebep olur.

force-response-1.0

HTTP/1.0 isteği yapan istemcilere HTTP/1.0 yanıtı verilmesini zorunlu kılar. AOL vekillerindeki bir sorun nedeniyle gerçeklenmiştir. Bazı HTTP/1.0 istemciler HTTP/1.1 yanıtlarında doğru davranmayabilirler; bu değişken atanarak bunların sorunları giderilebilir.

gzip-only-text/html

Bu değişkene "1" değeri atandığında text/html’den farklı içerik türleri için mod_deflate modülü tarafından sağlanan DEFLATE çıktı süzgeci iptal edilir. Sıkıştırılmış olarak saklanan dosyalar kullanıyorsanız bu değişkeni mod_negotiation modülü de dikkate alır (kimliğine bakarak sadece gzip için değil, tüm kodlamalar için bunu yapar).

no-gzip

Bu değişken atandığında, mod_deflate modülünün DEFLATE süzgeci kapatılır ve mod_negotiation modülü kodlanmış kaynak teslimatını reddeder.

no-cache

2.2.12 sürümünden beri kullanılabilmektedir.

Atandığı takdirde, mod_cache artık önbelleklenebilecek yanıtları kaydetmeyecektir. Bu ortam değişkeni bir yanıtın halihazırda mevcut bir isteğe sunulmak üzere önbellekte olup olmadığından etkilenmez.

nokeepalive

Bu değişken atandığında, KeepAlive yönergesi iptal edilir.

prefer-language

Değer olarak en, ja veya x-klingon gibi bir dil kısaltması verilerek atanmışsa mod_negotiation modülünün normal davranışını değiştirerek belirtilen dilde bir teslimat yapılmaya çalışılır. Böyle bir belge yoksa normal uzlaşım süreci uygulanır.

redirect-carefully

İstemciye bir yönlendirme gönderirken sunucuyu daha dikkatli olmaya zorlar. Bu genellikle istemcinin yönlendirmeler konusunda sorunlu olduğu bilindiği takdirde yararlı olur. Bu değişkenin gerçeklenme sebebi, dizin kaynaklarına yönlendirmeler için DAV yöntemlerini kullanan Microsoft'un WebFolders yazılımındaki bir sorundur.

suppress-error-charset

2.0.54 sürümünden beri mevcuttur.

Apache bir isteğe bir yönlendirme ile yanıt verdiğinde istemci yönlendirmeyi kendiliğinden yapmaz veya yapamazsa kullanıcıya yanıtla birlikte gönderilen metin gösterilir. Apache normal olarak bu metni ISO-8859-1 ile kodlar.

Ancak, yönlendirmenin yapıldığı sayfa farklı bir karakter kümesine sahipse bazı tarayıcı sürümleri asıl sayfanın karakter kodlaması yerine yönlendirmenin kodlamasını kullanmaya çalışırlar. Bu özellikle Yunanca gibi dillerde hedef sayfanın hatalı yorumlanmasına yol açar.

Bu ortam değişkeninin atanması Apache’nin yönlendirme için karakter kümesi belirtmemesini sağlamak suretiyle hatalı tarayıcıların hedef sayfayı yanlış karakter kodlamasıyla yorumlamasını önler.

Güvenlik Uyarısı

Hata sayfalarının bir karakter kümesi belirtilmeksizin yollanması, HTTP/1.1 belirtimine uymayan ve karakter kümesini içeriğe bakarak tahmin etmeye çalışan tarayıcılarda (MSIE) karşı siteden betik saldırısı yorumuna sebep olabilir. Girdi verisindeki UTF-7 içerik (istek betimleyici gibi) karşı siteden betik saldırılarını engellemek için tasarlanmış normal önceleme mekanizmalarıyla öncelenmeyeceği için böyle tarayıcılar UTF-7 karakter kodlaması kullanılarak kolayca aldatılabilir.

force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked ve proxy-sendcl, proxy-chain-auth, proxy-interim-response, proxy-initial-not-pooled

Bu yönergeler mod_proxy modülünün normal protokol davranışını değiştirirler. Daha ayrıntılı bilgi için mod_proxy ve mod_proxy_http belgelerine bakınız.

Örnekler

Bozuk başlıkların CGI betiklerine aktarılması

2.4 sürümünden itibaren, mod_cgi modülü ve diğer modüllerde HTTP başlıklarının ortam değişkenlerine dönüştürülmesi bağlamında Apache daha seçici davranmaktadır. Önce HTTP başlığındaki geçersiz karakterlerin tamamı altçizgilere dönüştürülür. Bu, başlık zerki yoluyla yapılan karşı-site-betiklerini-çalıştırma saldırısını önlemeye yöneliktir. (Bakınız: Unusual Web Bugs, slide 19/20).

Bozuk başlıklar gönderdiği halde bunlara dokunulmamasını gerektiren bir istemciniz varsa, mod_setenvif ve mod_headers modüllerinin sunduğu yapıyı örnekteki gibi kullanarak bu sorunun üstesinden gelebilirsiniz:

#
# Aşağıdaki satırlarla bir istemcinin gönderdiği bozuk
# Accept_Encoding başlıklarının istenildiği gibi işlenmesi
# sağlanabilir.
#
SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1
RequestHeader set Accept-Encoding %{fix_accept_encoding}e env=fix_accept_encoding

Protokolü yanlış yorumlayan tarayıcıların davranışlarının değiştirilmesi

Önceki sürümlerde bilinen istemci davranışlarına karşı önlem olarak aşağıdaki satırların httpd.conf içinde bulunması önerilirdi. Fakat, böyle tarayıcılar artık ortalıkta görünmediğinden bu yapılandırmaya da artık gerek kalmamıştır.

#
# Aşağıdaki yönergeler normal HTTP yanıt davranışını değiştirirler.
# İlk yönerge Netscape 2.x ve kendini öyle gösteren tarayıcılar için
# kalıcı bağlantıyı (keepalive) iptal eder. İkinci yönerge ise HTTP/1.1
# protokolü bozuk olan ve 301/302 durum kodlu yönlendirme yanıtları
# kullanıldığında kalıcı bağlantıları gerektiği gibi desteklemeyen
# Microsoft Internet Explorer 4.0b2 içindir.
#
BrowserMatch "Mozilla/2" nokeepalive
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0

#
# Aşağıdaki yönergeler HTTP/1.0 yanıtlarından başkasına yabancı olan
# tarayıcılara HTTP/1.1 yanıtlarının gönderilmesini iptal eder.
#
BrowserMatch "RealPlayer 4\.0" force-response-1.0
BrowserMatch "Java/1\.0" force-response-1.0
BrowserMatch "JDK/1\.0" force-response-1.0

Resim isteklerinin erişim günlüğüne kaydedilmemesi

Bu örnek resim isteklerinin erişim günlüğüne yazılmasını engeller. Bu örnek değiştirilerek belli dizinlerin veya belli konaklardan gelen isteklerin günlüğe kaydedilmesini engellemek amacıyla da kullanılabilir.

SetEnvIf Request_URI \.gif image-request
SetEnvIf Request_URI \.jpg image-request
SetEnvIf Request_URI \.png image-request
CustomLog logs/access_log common env=!image-request

“Resim Hırsızlığı” için önlem alınması

Bu örnekte sunucunuzda bulunmayan sayfalarda sunucunuzdaki resimlerin kullanılmasının nasıl önleneceği gösterilmiştir. Bu yapılandırma önerilmemekle birlikte nadir durumlarda işe yarar. Tüm resimlerin /siteler/resimler dizini altında tutulduğu varsayılmıştır.

SetEnvIf Referer "^http://www\.example\.com/" local_referal
# Referrer bilgisi göndermeyen tarayıcılara izin verelim
SetEnvIf Referer "^$" local_referal
<Directory "/siteler/resimler">
  Require env local_referal
</Directory>

Bu teknik hakkında daha ayrıntılı bilgi edinmek için ServerWatch üzerindeki "Diğer sitelerin sizin resimlerinizle donatılmasını engellemek" belgesine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Expressions in Apache HTTP Server - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Expressions in Apache HTTP Server

Historically, there are several syntax variants for expressions used to express a condition in the different modules of the Apache HTTP Server. There is some ongoing effort to only use a single variant, called ap_expr, for all configuration directives. This document describes the ap_expr expression parser.

The ap_expr expression is intended to replace most other expression variants in HTTPD. For example, the deprecated SSLRequire expressions can be replaced by Require expr.

See also

  • <If>
  • <ElseIf>
  • <Else>
  • ErrorDocument
  • Alias
  • ScriptAlias
  • Redirect
  • AuthBasicFake
  • AuthFormLoginRequiredLocation
  • AuthFormLoginSuccessLocation
  • AuthFormLogoutLocation
  • RewriteCond
  • SetEnvIfExpr
  • Header
  • RequestHeader
  • FilterProvider
  • Require expr
  • Require ldap-user
  • Require ldap-group
  • Require ldap-dn
  • Require ldap-attribute
  • Require ldap-filter
  • Require dbd-group
  • Require dbm-group
  • Require group
  • Require host
  • SSLRequire
  • LogMessage
  • mod_include

Grammar in Backus-Naur Form notation

Backus-Naur Form (BNF) is a notation technique for context-free grammars, often used to describe the syntax of languages used in computing. In most cases, expressions are used to express boolean values. For these, the starting point in the BNF is expr. However, a few directives like LogMessage accept expressions that evaluate to a string value. For those, the starting point in the BNF is string.

expr        ::= "true" | "false"
              | "!" expr
              | expr "&&" expr
              | expr "||" expr
              | "(" expr ")"
              | comp

comp        ::= stringcomp
              | integercomp
              | unaryop word
              | word binaryop word
              | word "in" "{" wordlist "}"
              | word "in" listfunction
              | word "=~" regex
              | word "!~" regex

stringcomp  ::= word "==" word
              | word "!=" word
              | word "<"  word
              | word "<=" word
              | word ">"  word
              | word ">=" word

integercomp ::= word "-eq" word | word "eq" word
              | word "-ne" word | word "ne" word
              | word "-lt" word | word "lt" word
              | word "-le" word | word "le" word
              | word "-gt" word | word "gt" word
              | word "-ge" word | word "ge" word

wordlist    ::= word
              | wordlist "," word

word        ::= word "." word
              | digit
              | "'" string "'"
              | """ string """
              | variable
              | rebackref
              | function

string      ::= stringpart
              | string stringpart

stringpart  ::= cstring
              | variable
              | rebackref

cstring     ::= ...
digit       ::= [0-9]+

variable    ::= "%{" varname "}"
              | "%{" funcname ":" funcargs "}"

rebackref   ::= "$" [0-9]

function     ::= funcname "(" word ")"

listfunction ::= listfuncname "(" word ")"

Variables

The expression parser provides a number of variables of the form %{HTTP_HOST}. Note that the value of a variable may depend on the phase of the request processing in which it is evaluated. For example, an expression used in an <If > directive is evaluated before authentication is done. Therefore, %{REMOTE_USER} will not be set in this case.

The following variables provide the values of the named HTTP request headers. The values of other headers can be obtained with the req function. Using these variables may cause the header name to be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function may be used to circumvent this behavior.

Name
HTTP_ACCEPT
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_REFERER
HTTP_USER_AGENT

Other request related variables

Name | Description
REQUEST_METHOD | The HTTP method of the incoming request (e.g. GET)
REQUEST_SCHEME | The scheme part of the request's URI
REQUEST_URI | The path part of the request's URI
DOCUMENT_URI | Same as REQUEST_URI
REQUEST_FILENAME | The full local filesystem path to the file or script matching the request, if this has already been determined by the server at the time REQUEST_FILENAME is referenced. Otherwise, such as when used in virtual host context, the same value as REQUEST_URI
SCRIPT_FILENAME | Same as REQUEST_FILENAME
LAST_MODIFIED | The date and time of last modification of the file in the format 20101231235959, if this has already been determined by the server at the time LAST_MODIFIED is referenced.
SCRIPT_USER | The user name of the owner of the script.
SCRIPT_GROUP | The group name of the group of the script.
PATH_INFO | The trailing path name information, see AcceptPathInfo
QUERY_STRING | The query string of the current request
IS_SUBREQ | "true" if the current request is a subrequest, "false" otherwise
THE_REQUEST | The complete request line (e.g., "GET /index.html HTTP/1.1")
REMOTE_ADDR | The IP address of the remote host
REMOTE_HOST | The host name of the remote host
REMOTE_USER | The name of the authenticated user, if any (not available during <If >)
REMOTE_IDENT | The user name set by mod_ident
SERVER_NAME | The ServerName of the current vhost
SERVER_PORT | The server port of the current vhost, see ServerName
SERVER_ADMIN | The ServerAdmin of the current vhost
SERVER_PROTOCOL | The protocol used by the request
DOCUMENT_ROOT | The DocumentRoot of the current vhost
AUTH_TYPE | The configured AuthType (e.g. "basic")
CONTENT_TYPE | The content type of the response (not available during <If >)
HANDLER | The name of the handler creating the response
HTTP2 | "on" if the request uses http/2, "off" otherwise
HTTPS | "on" if the request uses https, "off" otherwise
IPV6 | "on" if the connection uses IPv6, "off" otherwise
REQUEST_STATUS | The HTTP error status of the request (not available during <If >)
REQUEST_LOG_ID | The error log id of the request (see ErrorLogFormat)
CONN_LOG_ID | The error log id of the connection (see ErrorLogFormat)
CONN_REMOTE_ADDR | The peer IP address of the connection (see the mod_remoteip module)
CONTEXT_PREFIX |
CONTEXT_DOCUMENT_ROOT |

Misc variables

Name | Description
TIME_YEAR | The current year (e.g. 2010)
TIME_MON | The current month (1, ..., 12)
TIME_DAY | The current day of the month
TIME_HOUR | The hour part of the current time (0, ..., 23)
TIME_MIN | The minute part of the current time
TIME_SEC | The second part of the current time
TIME_WDAY | The day of the week (starting with 0 for Sunday)
TIME | The date and time in the format 20101231235959
SERVER_SOFTWARE | The server version string
API_VERSION | The date of the API version (module magic number)

Some modules register additional variables, see e.g. mod_ssl.

Binary operators

With the exception of some built-in comparison operators, binary operators have the form "-[a-zA-Z][a-zA-Z0-9_]+", i.e. a minus and at least two characters. The name is not case sensitive. Modules may register additional binary operators.

Comparison operators

Name | Alternative | Description
== | = | String equality
!= |  | String inequality
< |  | String less than
<= |  | String less than or equal
> |  | String greater than
>= |  | String greater than or equal
-eq | eq | Integer equality
-ne | ne | Integer inequality
-lt | lt | Integer less than
-le | le | Integer less than or equal
-gt | gt | Integer greater than
-ge | ge | Integer greater than or equal

Other binary operators

Name | Description
-ipmatch | IP address matches address/netmask
-strmatch | left string matches pattern given by right string (containing wildcards *, ?, [])
-strcmatch | same as -strmatch, but case insensitive
-fnmatch | same as -strmatch, but slashes are not matched by wildcards

Unary operators

Unary operators take one argument and have the form "-[a-zA-Z]", i.e. a minus and one character. The name is case sensitive. Modules may register additional unary operators.

Name | Description | Restricted
-d | The argument is treated as a filename. True if the file exists and is a directory | yes
-e | The argument is treated as a filename. True if the file (or dir or special) exists | yes
-f | The argument is treated as a filename. True if the file exists and is regular file | yes
-s | The argument is treated as a filename. True if the file exists and is not empty | yes
-L | The argument is treated as a filename. True if the file exists and is symlink | yes
-h | The argument is treated as a filename. True if the file exists and is symlink (same as -L) | yes
-F | True if string is a valid file, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance! |
-U | True if string is a valid URL, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance! |
-A | Alias for -U |
-n | True if string is not empty |
-z | True if string is empty |
-T | False if string is empty, "0", "off", "false", or "no" (case insensitive). True otherwise. |
-R | Same as "%{REMOTE_ADDR} -ipmatch ...", but more efficient |

The operators marked as "restricted" are not available in some modules like mod_include.

Functions

Normal string-valued functions take one string as argument and return a string. Functions names are not case sensitive. Modules may register additional functions.

Name | Description | Restricted
req, http | Get HTTP request header; header names may be added to the Vary header, see below |
req_novary | Same as req, but header names will not be added to the Vary header |
resp | Get HTTP response header |
reqenv | Lookup request environment variable (as a shortcut, v can be used too to access variables). |
osenv | Lookup operating system environment variable |
note | Lookup request note |
env | Return first match of note, reqenv, osenv |
tolower | Convert string to lower case |
toupper | Convert string to upper case |
escape | Escape special characters in %hex encoding |
unescape | Unescape %hex encoded string, leaving encoded slashes alone; return empty string if %00 is found |
base64 | Encode the string using base64 encoding |
unbase64 | Decode base64 encoded string, return truncated string if 0x00 is found |
md5 | Hash the string using MD5, then encode the hash with hexadecimal encoding |
sha1 | Hash the string using SHA1, then encode the hash with hexadecimal encoding |
file | Read contents from a file (including line endings, when present) | yes
filesize | Return size of a file (or 0 if file does not exist or is not regular file) | yes

The functions marked as "restricted" are not available in some modules like mod_include.

When the functions req or http are used, the header name will automatically be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function can be used to prevent names from being added to the Vary header.

In addition to string-valued functions, there are also list-valued functions which take one string as argument and return a wordlist, i.e. a list of strings. The wordlist can be used with the special -in operator. Functions names are not case sensitive. Modules may register additional functions.

There are no built-in list-valued functions. mod_ssl provides PeerExtList. See the description of SSLRequire for details (but PeerExtList is also usable outside of SSLRequire).

Example expressions

The following examples show how expressions might be used to evaluate requests:

# Compare the host name to example.com and redirect to www.example.com if it matches
<If "%{HTTP_HOST} == 'example.com'">
    Redirect permanent "/" "http://www.example.com/"
</If>

# Force text/plain if requesting a file with the query string contains 'forcetext'
<If "%{QUERY_STRING} =~ /forcetext/">
    ForceType text/plain
</If>

# Only allow access to this content during business hours
<Directory "/foo/bar/business">
    Require expr %{TIME_HOUR} -gt 9 && %{TIME_HOUR} -lt 17
</Directory>

# Check a HTTP header for a list of values
<If "%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }">
    Header set matched true
</If>

# Check an environment variable for a regular expression, negated.
<If "! reqenv('REDIRECT_FOO') =~ /bar/">
    Header set matched true
</If>

# Check result of URI mapping by running in Directory context with -f
<Directory "/var/www">
    AddEncoding x-gzip gz
<If "-f '%{REQUEST_FILENAME}.unzipme' && ! %{HTTP:Accept-Encoding} =~ /gzip/">
      SetOutputFilter INFLATE
</If>
</Directory>

# Function examples in boolean context
<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
  Header set checksum-matched true
</If>
<If "md5('foo') == replace('md5:XXXd18db4cc2f85cedef654fccc4a4d8', 'md5:XXX', 'acb')">
  Header set checksum-matched-2 true
</If>

# Function example in string context
Header set foo-checksum "expr=%{md5:foo}"

# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

Other

Name | Alternative | Description
-in | in | string contained in wordlist
/regexp/ | m#regexp# | Regular expression (the second form allows different delimiters than /)
/regexp/i | m#regexp#i | Case insensitive regular expression
$0 ... $9 |  | Regular expression backreferences

Regular expression backreferences

The strings $0 ... $9 allow to reference the capture groups from a previously executed, successfully matching regular expressions. They can normally only be used in the same expression as the matching regex, but some modules allow special uses.

Comparison with SSLRequire

The ap_expr syntax is mostly a superset of the syntax of the deprecated SSLRequire directive. The differences are described in SSLRequire's documentation.

Version History

The req_novary function is available for versions 2.4.4 and later.


Apache Eylemcilerinin Kullanımı - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache Eylemcilerinin Kullanımı

Bu belgede Apache Eylemcilerinin kullanımı açıklanmıştır.

Eylemci Nedir?

İlgili Modüller İlgili Yönergeler
  • mod_actions
  • mod_asis
  • mod_cgi
  • mod_imagemap
  • mod_info
  • mod_mime
  • mod_negotiation
  • mod_status
  • Action
  • AddHandler
  • RemoveHandler
  • SetHandler

Bir eylemci bir dosya çağrıldığında uygulanacak eylemin Apache dahilindeki gösterimidir. Genellikle dosyaların kendi türüne bağlı olarak örtük eylemcileri vardır. Normalde tüm dosyalar basitçe sunucu tarafından sunulurlar, fakat bazı dosya türleri normalden farklı şekilde ele alınırlar.

Eylemciler, dosya türünden bağımsız olarak dosyanın bulunduğu yere veya dosya ismi uzantısına göre de yapılandırılabilirler. Gerek, zarif bir çözüm oluşuyla gerekse, hem dosya türünü hem de bir dosya ile ilişkili bir eylemciyi mümkün kılması sebebiyle bunun getirisi daha yüksektir. (Ayrıca, çok uzantılı dosyalara da bakınız.)

Eylemciler sunucu içinde derlenebileceği gibi bir modül olarak ya da Action yönergesi ile de sunucuya dahil edilebilirler. Standart dağıtımda bulunan yerleşik eylemciler şunlardır:

  • default-handler: Dosyayı, öntanımlı olarak durağan içeriği işlemekte kullanılan default_handler() işlevini kullanarak gönderir. (core)
  • send-as-is: Dosyayı HTTP başlıklarıyla olduğu gibi gönderir. (mod_asis)
  • cgi-script: Dosyayı bir CGI betiği olarak ele alır. (mod_cgi)
  • imap-file: Dosyayı bir resim eşleme kuralları dosyası olarak çözümler. (mod_imagemap)
  • server-info: Sunucunun yapılandırma bilgisini döndürür. (mod_info)
  • server-status: Sunucunun durum raporunu döndürür. (mod_status)
  • type-map: Dosyayı içerik uzlaşımı için bir tür eşlem dosyası olarak çözümler. (mod_negotiation)

Örnekler

Bir CGI betiği kullanarak durağan içeriğin değiştirilmesi

Aşağıdaki yönergeler sayesinde, html uzantılı dosyalar için yapılan istekler footer.pl CGI betiğininin çalıştırılmasına sebep olacaktır.

Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html

Bu yapılandırmayla, istenen belgenin özgün haliyle mi (yeri PATH_TRANSLATED ortam değişkenindedir) yoksa istenen değişiklikler veya eklemeler yapıldıktan sonra mı gönderileceğinden CGI betiği sorumlu olacaktır.

HTTP başlıklı dosyalar

Aşağıdaki yönergeler kendi HTTP başlıklarını içeren dosyalar için kullanılan send-as-is eylemcisini etkinleştirmek amacıyla kullanılmıştır. /siteler/htdocs/asis/ dizinindeki tüm dosyalar dosya ismi uzantılarına bakılmaksızın send-as-is eylemcisi tarafından işleme sokulacaktır.

<Directory "/web/htdocs/asis">
    SetHandler send-as-is
</Directory>

Yazılım Geliştirenler İçin

Eylemci özellikleri gerçeklenirken kullanılmak üzere Apache API’ye bir ekleme yapılmıştır. Özellikle de, request_rec yapısına yeni bir kayıt eklenmiştir:

char *handler

Modülünüzün bir eylemciyi devreye sokmasını isterseniz, tek yapacağınız isteğin invoke_handler aşamasının hemen öncesinde r->handler alanına eylemcinin ismini atamak olacaktır. Eylemciler daha önce de bahsedildiği gibi bir içerik türü yerine bir eylemci ismi kullanılarak gerçeklenirler. Çok gerekli olmamakla birlikte, eylemciler için kullanılan adlandırma uzlaşımları gereğince, ismi oluşturan sözcükler, ortam türü isim alanını ihlal etmemek amacıyla bölü imleri ile değil tire imleri ile ayrılırlar.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Süzgeçler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Süzgeçler

Bu belge, Apache’de süzgeç kullanımı hakkındadır.

Apache 2’de Süzme İşlemi

İlgili Modüller İlgili Yönergeler
  • mod_filter
  • mod_deflate
  • mod_ext_filter
  • mod_include
  • mod_charset_lite
  • mod_reflector
  • mod_buffer
  • mod_data
  • mod_ratelimit
  • mod_reqtimeout
  • mod_request
  • mod_sed
  • mod_substitute
  • mod_xml2enc
  • mod_proxy_html
  • FilterChain
  • FilterDeclare
  • FilterProtocol
  • FilterProvider
  • AddInputFilter
  • AddOutputFilter
  • RemoveInputFilter
  • RemoveOutputFilter
  • ReflectorHeader
  • ExtFilterDefine
  • ExtFilterOptions
  • SetInputFilter
  • SetOutputFilter

Apache 2.0 ve sonrasında mevcut olan Süzgeç Zinciri, uygulamaların nereden geldiğine bakmaksızın gelen ve giden verileri oldukça esnek ve yapılandırılabilir tarzda işlemesini mümkün kılar. Böylece, gelen veriyi bir takım ön işlemlerden geçirebilir, giden veriyi de son bir defa bazı işlemlere sokabiliriz. Bu işlem temel olarak geleneksel istek işleme aşamalarından bağımsızdır.

Süzgeçler, İstek işleme eksenine dik bir veri eksenine peş peşe yerleştirilebilir.

Standard Apache dağıtımıyla gelen süzgeç uygulamalarından bazıları:

  • mod_include, sunucu taraflı içerik yerleştirmeyi gerçekler.
  • mod_ssl, SSL şifrelemesini gerçekler (https).
  • mod_deflate, veri sıkıştırma/açma işlemlerini çalışma anında gerçekleştirir.
  • mod_charset_lite, karakter kümeleri arasında dönüşümü gerçekleştirir.
  • mod_ext_filter, harici bir yazılımı bir süzgeç olarak çalıştırır.

Apache, bunlardan başka, bayt dizilerinin elde edilmesi ve içeriğin bölünmesi gibi işlemleri gerçekleştirmek için bir takım dahili süzgeçler de kullanabilir.

Üçüncü parti süzgeç modülleri tarafından gerçeklenmiş çok geniş bir uygulama alanı mevcuttur; modules.apache.org ve benzerlerinden temin edilebilecek bu tür modüllerden bazılarının uygulama alanları:

  • HTML ve XML belgelerin işlenmesi ve yazılması
  • XSLT dönüşümleri ve XInclude’lar
  • XML İsim-alanı desteği
  • HTML Formlarının çözümlenmesi ve sunucuya dosya yükleme
  • Resim işleme
  • PHP betikleri gibi zararlı olabilecek uygulamalardan korunma
  • Metin düzenleme ve arama işlemleri

Akıllı Süzme

Farklı süzgeç üreticilerinin uygulamaları istek işlemenin durumuna bağlı olarak akıllıca uygulanabilir.

mod_filter, Apache 2.1 ve sonrasında mevcut olup, süzgeç zincirinin çalışma anında devingen olarak yapılandırılabilmesini mümkün kılar. Böylece, örneğin, bir vekili, özgün sunucunun ne göndereceğini bilmeden HTML’yi bir HTML süzgeciyle yazmaya ve JPEG resimleri tamamen farklı bir süzgeçten geçirmeye ayarlayabilirsiniz. Bu, asıl içeriğe bağlı olarak çalışma anında içeriği farklı içerik sağlayıcılara dağıtan bir süzgeç düzeneği kullanılarak çalışır. Bir süzgeç, doğrudan zincire yerleştirilip koşulsuz olarak çalıştırılabileceği gibi bir içerik sağlayıcı gibi kullanılarak zincire devingen olarak yerleştirilebilir. Örneğin:

  • Bir HTML işleme süzgeci sadece içerik text/html veya application/xhtml+xml olduğu takdirde çalışır.
  • Bir sıkıştırma süzgeci sadece girdi sıkıştırılabilir nitelikteyse ve sıkıştırılmamışsa çalışır.
  • Bir karakter kümesi dönüşüm süzgeci, bir metin belgesi istenen karakter kümesine sahip değilse zincire yerleştirilir.

Süzgeçleri bir HTTP Hizmeti gibi göstermek

Süzgeçler, istemciden kaynaklanan içeriği işlemekte kullanılabileceği gibi mod_reflector modülü kullanılarak sunucudan kaynaklanan içeriği işlemekte de kullanılabilir.

mod_reflector istemcilerden gelen POST isteklerini kabul eder ve çıktı süzgeç yığıtı yoluyla istemciye aktararak, POST isteği içinde alınan içerik istek gövdesini yanıt içinde geri gönderir.

Bu teknik, bir çıktı süzgeciyle istek gövdesinde gerekli dönüşümün sağlandığı durumda, bir uygulama sunucusu yığıtı içinde çalışan bir http hizmetinin yerine de kullanılabilir. Örneğin, mod_deflate modülü genel bir sıkıştırma hizmeti sağlamakta kullanılabilir veya bir resim dönüştürme süzgeci bir resim dönüşüm hizmeti haline getirilebilir.

Süzgeçlerin Kullanımı

Süzgeçler iki şekilde kullanılır: Basit ve Devingen. Genelde ikisinden biri kullanılır; karışık kullanılırsa istenmeyen sonuçlara yol açabilir (ise de, basit girdi süzme ile çıktı süzme işlemi basit olsun olmasın karışık kullanılabilir).

Basit yol, girdi süzgeçlerini yapılandırmanın tek yoludur ve bir durağan süzgeç zincirinin gerektiği yerlerde çıktı süzgeçleri için yeterlidir. İlgili yönergeler: SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter ve RemoveOutputFilter.

Devingen yol, mod_filter belgesinde açıklandığı gibi, çıktı süzgeçlerinin hem durağan hem de esnek ve devingen olarak yapılandırılabilmesini mümkün kılar. İlgili yönergeler: FilterChain, FilterDeclare ve FilterProvider.

AddOutputFilterByType yönergesi hala desteklenmekteyse de kullanımı artık önerilmemektedir. Onun yerine devingen yapılandırma kullanınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Shared Object Cache in Apache HTTP Server - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Shared Object Cache in Apache HTTP Server

The Shared Object Cache provides a means to share simple data across all a server's workers, regardless of thread and process models. It is used where the advantages of sharing data across processes outweigh the performance overhead of inter-process communication.

Shared Object Cache Providers

The shared object cache as such is an abstraction. Four different modules implement it. To use the cache, one or more of these modules must be present, and configured.

The only configuration required is to select which cache provider to use. This is the responsibility of modules using the cache, and they enable selection using directives such as CacheSocache, AuthnCacheSOCache, SSLSessionCache, and SSLStaplingCache.

Currently available providers are:

"dbm" (mod_socache_dbm)
This makes use of a DBM hash file. The choice of underlying DBM used may be configurable if the installed APR version supports multiple DBM implementations.
"dc" (mod_socache_dc)
This makes use of the distcache distributed session caching libraries.
"memcache" (mod_socache_memcache)
This makes use of the memcached high-performance, distributed memory object caching system.
"shmcb" (mod_socache_shmcb)
This makes use of a high-performance cyclic buffer inside a shared memory segment.

The API provides the following functions:

const char *create(ap_socache_instance_t **instance, const char *arg, apr_pool_t *tmp, apr_pool_t *p);
Create a session cache based on the given configuration string. The instance pointer returned in the instance paramater will be passed as the first argument to subsequent invocations.
apr_status_t init(ap_socache_instance_t *instance, const char *cname, const struct ap_socache_hints *hints, server_rec *s, apr_pool_t *pool)
Initialize the cache. The cname must be of maximum length 16 characters, and uniquely identifies the consumer of the cache within the server; using the module name is recommended, e.g. "mod_ssl-sess". This string may be used within a filesystem path so use of only alphanumeric [a-z0-9_-] characters is recommended. If hints is non-NULL, it gives a set of hints for the provider. Return APR error code.
void destroy(ap_socache_instance_t *instance, server_rec *s)
Destroy a given cache instance object.
apr_status_t store(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, apr_time_t expiry, unsigned char *data, unsigned int datalen, apr_pool_t *pool)
Store an object in a cache instance.
apr_status_t retrieve(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, unsigned char *data, unsigned int *datalen, apr_pool_t *pool)
Retrieve a cached object.
apr_status_t remove(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, apr_pool_t *pool)
Remove an object from the cache.
void status(ap_socache_instance_t *instance, request_rec *r, int flags)
Dump the status of a cache instance for mod_status.
apr_status_t iterate(ap_socache_instance_t *instance, server_rec *s, void *userctx, ap_socache_iterator_t *iterator, apr_pool_t *pool)
Dump all cached objects through an iterator callback.


SuEXEC Desteği - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

SuEXEC Desteği

SuEXEC özelliği, Apache HTTP Sunucusu kullanıcılarına CGI ve SSI programlarını sunucunun aidiyetinde çalıştığı kullanıcıdan farklı bir kullanıcının aidiyetinde çalıştırma olanağı verir. Normalde, CGI ve SSI programlarını çalıştıranla sunucuyu çalıştıran aynı kullanıcıdır.

Gerektiği gibi kullanıldığında bu özellik, kullanıcılara CGI ve SSI programlarını çalıştırma ve geliştirmeye izin vermekle ortaya çıkan güvenlik risklerini azaltır. Bununla birlikte, suEXEC gerektiği gibi yapılandırılmadığı takdirde bazı sorunlara yol açabilir ve bilgisayar güvenliğinizde yeni delikler ortaya çıkmasına sebep olabilir. Güvenlikle ilgili mevcut sorunlarla başa çıkmada ve setuid root programları yönetmekte bilgi ve deneyim sahibi değilseniz suEXEC kullanmayı kesinlikle düşünmemenizi öneririz.

Başlamadan önce

Belgeye balıklama dalmadan önce, suexec'i kullanacağınız ortam ve kendiniz hakkında yapılmış çeşitli kabuller hakkında bilgi sahibi olmalısınız.

Öncelikle, üzerinde setuid va setgid işlemlerinin yapılabildiği Unix türevi bir işletim sistemi kullandığınızı varsayıyoruz. Tüm komut örnekleri buna dayanarak verilmiştir. Bu desteğe sahip başka platformlar varsa onlardaki yapılandırma burada anlattığımız yapılandırmadan farklı olabilir.

İkinci olarak, bilgisayarınızın güvenliği ve yönetimi ile ilgili bazı temel kavramları bildiğinizi kabul ediyoruz. Buna setuid/setgid işlemlerinin sisteminiz ve güvenlik seviyesi üzerindeki etkilerini bilmek dahildir.

Üçüncü olarak, suEXEC kodunun değiştirilmemiş bir sürümünü kullandığınızı varsayıyoruz. Tüm suEXEC kodu, geliştiricilerin yanında sayısız beta kullanıcısı tarafından dikkatle incelenmiş ve denenmiştir. Kodların hem basit hem de sağlam bir şekilde güvenli olması için gerekli tüm önlemler alınmıştır. Bu kodun değiştirilmesi beklenmedik sorunlara ve yeni güvenlik risklerine yol açabilir. Özellikle güvenlikle ilgili programlarda deneyimli değilseniz suEXEC kodunda kesinlikle bir değişiklik yapmamalısınız. Değişiklik yaparsanız kodlarınızı gözden geçirmek ve tartışmak üzere Apache HTTP Sunucusu geliştirme ekibi ile paylaşmanızı öneririz.

Dördüncü ve son olarak, Apache HTTP Sunucusu geliştirme ekibinin suEXEC’i öntanımlı httpd kurulumunun bir parçası yapmama kararından bahsetmek gerekir. Bunun sonucu olarak, suEXEC yapılandırması sistem yöneticisinin ayrıntılı bir incelemesini gerektirir. Gerekli incelemeden sonra yönetici tarafından suEXEC yapılandırma seçeneklerine karar verilip, normal yollardan sisteme kurulumu yapılır. Bu seçeneklerin belirlenmesi, suEXEC işlevselliğinin kullanımı sırasında sistem güvenliğini gerektiği gibi sağlamak için yönetici tarafından dikkatle saptanmayı gerektirir. Bu sürecin ayrıntılarının yöneticiye bırakılma sebebi, suEXEC kurulumunu, suEXEC’i dikkatle kullanacak yeterliliğe sahip olanlarla sınırlama beklentimizdir.

Hala bizimle misiniz? Evet mi? Pekala, o halde devam!

SuEXEC Güvenlik Modeli

SuEXEC yapılandırması ve kurulumuna girişmeden önce biraz da gerçekleşmesini istediğiniz güvenlik modelinin ayrıntıları üzerinde duralım. Böylece, suEXEC’in içinde olup bitenleri ve sisteminizin güvenliği için alınacak önlemleri daha iyi anlayabilirsiniz.

suEXEC işlevselliği, Apache HTTP Sunucusu tarafından gerektiği takdirde artalanda çalıştırılan bir setuid programa dayanır. Bu program, bir CGI veya SSI betiğine bir HTTP isteği yapıldığı zaman, bu betiği, yöneticinin ana sunucunun aidiyetinde çalıştığı kullanıcıdan farklı olarak seçtiği bir kullanıcının aidiyetinde çalıştırmak için çağrılır. Böyle bir istek geldiğinde, Apache httpd artalandaki setuid programına, HTTP isteği yapılan programın ismiyle beraber aidiyetinde çalışacağı kullanıcı ve grup kimliklerini de aktarır.

Artalanda çalıştırılan setuid program başarıyı ve başarısızlığı aşağıdaki süreci izleyerek saptar. Bunlardan herhangi biri başarısız olursa program başarısızlık durumunu günlüğe kaydeder ve bir hata vererek çıkar. Aksi takdirde çalışmaya devam eder.

  1. Setuid programı çalıştıran kullanıcı sistemin geçerli kullanıcılarından biri mi?

    Bu, setuid programı çalıştıran kullanıcının sistemin gerçek bir kullanıcısı olduğunudan emin olunmasını sağlar.

  2. Setuid program yeterli sayıda argümanla çağrılmış mı?

    Apache HTTP Sunucusunun artalanda çağırdığı setuid program ancak yeterli sayıda argüman sağlandığı takdirde çalışacaktır. Argümanların sayısını ve sırasını Apache HTTP sunucusu bilir. Eğer setuid program yeterli sayıda argümanla çağrılmamışsa ya kendisinde bir değişiklik yapılmıştır ya da kurulu Apache httpd çalıştırılabilirinin suEXEC ile ilgili kısmında yanlış giden bir şeyler vardır.

  3. Bu geçerli kullanıcının bu setuid programı çalıştırma yetkisi var mı?

    Sadece tek bir kullanıcı (Apache’nin aidiyetinde çalıştığı kullanıcı) bu programı çalıştırmaya yetkilidir.

  4. Hedef CGI veya SSI programı hiyerarşik olarak güvenliği bozacak bir dosya yolu üzerinde mi?

    Hedef CGI veya SSI programının dosya yolu '/' veya '..' ile başlıyor mu? Buna izin verilmez. Hedef CGI veya SSI programı suEXEC’in belge kök dizininde yer almalıdır (aşağıda --with-suexec-docroot=DİZİN seçeneğine bakınız).

  5. Hedef kullanıcı ismi geçerli mi?

    Hedef kullanıcı mevcut mu?

  6. Hedef grup ismi geçerli mi?

    Hedef grup mevcut mu?

  7. Hedef kullanıcı root değil, değil mi?

    Mevcut durumda, root kullanıcısının CGI/SSI programlarını çalıştırmasına izin verilmemektedir.

  8. Hedef kullanıcı kimliği asgari kullanıcı numarasından BÜYÜK mü?

    Asgari kullanıcı numarası yapılandırma sırasında belirtilir. Böylece CGI/SSI programlarını çalıştırmasına izin verilecek olası en düşük kullanıcı numarasını belirlemeniz mümkün kılınmıştır. Bu bazı “sistem” hesaplarını devreden çıkarmak için yararlıdır.

  9. Hedef grup root değil, değil mi?

    root grubunun CGI/SSI programlarını çalıştırmasına izin verilmemektedir.

  10. Hedef grup numarası asgari grup numarasından BÜYÜK mü?

    Asgari grup numarası yapılandırma sırasında belirtilir. Böylece CGI/SSI programlarını çalıştırmasına izin verilecek olası en düşük grup numarasını belirlemeniz mümkün kılınmıştır. Bu bazı “sistem” hesaplarını devreden çıkarmak için yararlıdır.

  11. Apache’nin artalanda çağırdığı setuid program hedef kullanıcı ve grubun aidiyetine geçebildi mi?

    Bu noktadan itibaren program setuid ve setgid çağrıları üzerinden hedef kullanıcı ve grubun aidiyetine geçer. Erişim grubu listesi de ayrıca kullanıcının üyesi olduğu tüm gruplara genişletilir.

  12. Hedef CGI/SSI programının bulunduğu dizine geçebildik mi?

    Dizin mevcut değilse dosyaları da içeremez. Hedef dizine geçemiyorsak bu, dizin mevcut olmadığından olabilir.

  13. Hedef dizin Apache için izin verilen yerlerden biri mi?

    İstek sunucunun normal bir bölümü için yapılmış olsa da istenen dizin acaba suEXEC’in belge kök dizini altında mı? Yani, istenen dizin, suEXEC’in aidiyetinde çalıştığı kullanıcının ev dizini altında bulunan, UserDir ile belirtilen dizinin altında mı? (suEXEC’in yapılandırma seçeneklerine bakınız).

  14. Hedef dizin başkaları tarafından yazılabilen bir dizin değil, değil mi?

    Başkaları da yazabilsin diye bir dizin açmıyoruz; dizin içeriğini sadece sahibi değiştirebilmelidir.

  15. Hedef CGI/SSI programı mevcut mu?

    Mevcut değilse çalıştırılamaz.

  16. Hedef CGI/SSI program dosyasına başkaları tarafından yazılamıyor, değil mi?

    Hedef CGI/SSI programının dosyasına sahibinden başka kimsenin bir şeyler yazmasını istemeyiz.

  17. Hedef CGI/SSI program setuid veya setgid değil, değil mi?

    UID/GID‘i tekrar değiştirecek programlar çalıştırmayı istemeyiz.

  18. Hedef kullanıcı/grup, programın kullanıcı/grubu ile aynı mı?

    Hedef kullanıcı dosyanın sahibi mi?

  19. İşlemlerin güvenle yapılabilmesi için süreç ortamını başarıyla temizleyebildik mi?

    suEXEC, sürecin çalışacağı ortama güvenli bir program çalıştırma yolu sağlamaktan başka, yapılandırma sırasında oluşturulan güvenli ortam değişkenleri listesinde isimleri bulunan ortam değişkenlerinden başkasını aktarmayacaktır.

  20. Hedef CGI/SSI programı haline gelip çalışabildik mi?

    Burası suEXEC’in bitip CGI/SSI programının başladığı yerdir.

Bu süreç suEXEC güvenlik modelinin standart işlemlerini oluşturur. Biraz zorlayıcı ve CGI/SSI tasarımına yeni kurallar ve sınırlamalar getiriyor olsa da düşünülen güvenliği adım adım sağlayacak şekilde tasarlanmıştır.

Düzgün bir suEXEC yapılandırmasının hangi güvenlik risklerinden kurtulmayı sağladığı ve bu güvenlik modelinin sunucu yapılandırmasıyla ilgili sorumluluklarınızı nasıl sınırlayabildiği hakkında daha ayrıntılı bilgi edinmek için bu belgenin "Uyarılar ve Örnekler" bölümüne bakınız.

suEXEC’in Yapılandırılması ve Kurulumu

Eğlence başlıyor.

suEXEC yapılandırma seçenekleri

--enable-suexec
Bu seçenek, hiçbir zaman öntanımlı olarak kurulmayan ve etkinleştirilmeyen suEXEC özelliğini etkin kılar. suEXEC özelliğini kullanma isteğinizi Apache’nin kabul edebilmesi için --enable-suexec seçeneğinin yanında en azından bir tane de --with-suexec-xxxxx seçeneği belirtilmiş olmalıdır.
--with-suexec-bin=YOL
Güvenlik sebebiyle suexec çalıştırılabilirinin bulunduğu yer sunucu koduna yazılır. Bu seçenekle öntanımlı yol değiştirilmiş olur. Örnek:
--with-suexec-bin=/usr/sbin/suexec
--with-suexec-caller=KULLANICI
Normalde httpd’nin aidiyetinde çalıştığı kullanıcıdır. Bu, suEXEC çalıştırıcısını çalıştırmasına izin verilen tek kullanıcıdır.
--with-suexec-userdir=DİZİN

Kullanıcıların ev dizinleri altında suEXEC’in erişmesine izin verilen alt dizinin yerini tanımlar. Bu dizin altında suEXEC kullanıcısı tarafından çalıştırılacak tüm programlar "güvenilir" olmalıdır. Eğer “basit” bir UserDir yönergesi kullanıyorsanız ( içinde “*” bulunmayan), bunun aynı dizin olması gerekir. Eğer burada belirtilen dizin, passwd dosyasında kullanıcı için belirtilmiş dizinin altında UserDir yönergesinde belirtilen dizin olmadığı takdirde suEXEC işini gerektiği gibi yapmayacaktır. Öntanımlı değer public_html’dir.

Eğer, sanal konaklarınızın herbiri farklı UserDir yönergeleri içeriyorsa burada belirtilecek dizinin üst dizininin hepsinde aynı olması gerekir. Aksi takdirde, "~kullanıcı" istekleri düzgün çalışmayacaktır.

--with-suexec-docroot=DİZİN
httpd için belge kök dizinini belirler. Bu, (UserDir’lardan başka) suEXEC için kullanılacak tek hiyerarşi olacaktır. Öntanımlı dizin sonuna "/htdocs" eklenmiş --datadir dizinidir. Yani, seçeneği "--datadir=/home/apache" olarak belirtmişseniz suEXEC çalıştırıcısı için belge kök dizini "/home/apache/htdocs" olur.
--with-suexec-uidmin=UID
suEXEC kullanıcısının kullanıcı kimliği olarak izin verilen en düşük değeri belirler. Çoğu sistemde bu ya 500’dür ya da 100; 100 öntanımlıdır.
--with-suexec-gidmin=GID
suEXEC kullanıcısının grup kimliği olarak izin verilen en düşük değeri belirler. Çoğu sistemde bu 100 olup, seçeneğin de öntanımlı değeridir.
--with-suexec-logfile=DOSYA
suEXEC hareketlerinin ve hatalarının kaydedileceği günlük dosyasının adını belirler (denetim ve hata ayıklama için kullanışlıdır). Öntanımlı günlük dosyası ismi "suexec_log" olup yeri (--logfiledir seçeneği ile belirtilen) günlük dosyaları dizinidir.
--with-suexec-safepath=YOL
CGI çalıştırılabilirlerine aktarılacak güvenilir PATH ortam değişkeninin değerini tanımlar. "/usr/local/bin:/usr/bin:/bin" öntanımlıdır.

SuEXEC çalıştırıcısının derlenmesi ve kurulumu

SuEXEC özelliğini --enable-suexec seçeneği ile etkinleştirdiyseniz make komutunu verdiğinizde httpd ile birlikte suexec çalıştırılabilir dosyası da derlenecektir.

Tüm bileşenler derlendikten sonra make install komutunu vererek kurulumu tamamlayabilirsiniz. suexec çalıştırılabilir dosyası --sbindir seçeneği ile tanımlanan dizine kurulacaktır; öntanımlı yeri /usr/local/apache2/bin/ dizinidir.

Kurulum adımında root yetkisine sahip olmanız gerektiğini unutmayın. Çalıştırıcıya kullanıcı kimliğinin atanabilmesi ve dosyanın sahibi olan kullanıcı kimliği ile çalıştırılabilmesini mümkün kılan bitinin etkin kılınabilmesi için kurulumun root tarafından yapılması önemlidir.

Paranoyak yetkilendirme

SuEXEC çalıştırıcısı kendini çalıştıran kullanıcının configure betiğine --with-suexec-caller seçeneği ile belirtilen kullanıcı olup olmadığına bakacaksa da, bu sınamanın da bir sistem veya kütüphane çağrısı ile istismar edilmiş olma ihtimali gözardı edilmemelidir. Bunun meydana gelmesini önlemek için ve genelde yapıldığı gibi dosyanın izinlerini suEXEC çalıştırıcısı sadece httpd'nin aidiyetinde çalıştığı grup tarafından çalıştırılacak şekilde ayarlayınız.

Örneğin, sunucunuz şöyle yapılandırılmışsa:

User www
Group webgroup

Ve suexec çalıştırılabilir de /usr/local/apache2/bin/ dizinine kurulmuşsa şu komutları vermelisiniz:

chgrp apache-grup /usr/local/apache2/bin/suexec
chmod 4750 /usr/local/apache2/bin/suexec

Böylece suEXEC çalıştırıcısını httpd’yi çalıştıran grubun üyelerinden başkasının çalıştıramayacağından emin olabilirsiniz.

suEXEC’in etkin kılınması ve iptal edilmesi

httpd başlatıldığı sırada suexec çalıştırıcısı için --sbindir seçeneği ile tanımlanan dizine bakar (seçeneğin öntanımlı değeri /usr/local/apache/sbin/suexec’tir). httpd düzgün yapılandırılmış bir suEXEC çalıştırıcısı bulduğu takdirde hata günlüğüne şöyle bir ileti yazacaktır:

[notice] suEXEC mechanism enabled (wrapper: /dosya/yolu/suexec)

Sunucu başlatıldığında bu ileti yazılmazsa sunucu ya çalıştırıcı programı umduğu yerde bulamamıştır ya da dosyanın setuid biti root tarafından etkin kılınmamıştır.

SuEXEC mekanizmasını etkin kılmak istediğiniz sunucu çalışmaktaysa sunucuyu önce öldürmeli sonra yeniden başlatmalısınız. Basit bir HUP veya USR1 sinyali ile yeniden başlamasını sağlamak yeterli olmayacaktır.

SuEXEC mekanizmasını iptal etmek için ise suexec dosyasını sildikten sonra httpd'yi öldürüp yeniden başlamalısınız.

SuEXEC’in kullanımı

CGI programlarına yapılan isteklerin suEXEC çalıştırıcısı tarafından yerine getirilebilmesi için sanal konağın bir SuexecUserGroup yönergesi içermesi veya isteğin mod_userdir tarafından işleme konulması gerekir.

Sanal Konaklar:
SuEXEC çalıştırıcısını farklı bir kullanıcı ile etkin kılmanın tek yolu VirtualHost bölümleri içinde SuexecUserGroup yönergesini kullanmaktır. Bu yönergede ana sunucuyu çalıştıran kullanıcıdan farklı bir kullanıcı belirterek ilgili sanal konak üzerinden CGI kaynakları için yapılan tüm isteklerin belirtilen kullanıcı ve grup tarafından çalıştırılması sağlanır. Bu yönergeyi içermeyen sanal konaklar için ana sunucunun kullanıcısı öntanımlıdır.

Kullanıcı dizinleri:
mod_userdir tarafından işleme sokulan tüm istekler için suEXEC çalıştırıcısı istek yapılan kullanıcı dizininin sahibinin aidiyetinde çalıştırılacaktır. Bu özelliğin çalışması için tek gereklilik, kullanıcının SuEXEC çalıştırıcısı için etkin kılınmış olması ve çalıştırıcının yukarıdaki güvenlik sınamalarından geçebilmesidir. Ayrıca, --with-suexec-userdir derleme seçeneğinin açıklamasına da bakınız.

SuEXEC ve hata ayıklama

SuEXEC çalıştırıcısı yukarıda değinildiği gibi günlük bilgilerini --with-suexec-logfile seçeneği ile belirtilen dosyaya yazacaktır. Çalıştırıcıyı doğru yapılandırarak kurduğunuzdan emin olmak istiyorsanız, yolunda gitmeyen şeyler var mı diye bu günlük dosyasına bakmayı ihmal etmeyin.

Uyarılar ve Örnekler

UYARI! Bu bölüm henüz bitmedi. Bu bölümün son hali için çevrimiçi belgelere bakınız.

SuEXEC çalıştırıcısından dolayı sunucu ayarlarına bazı sınırlamalar getiren bir kaç önemli nokta mevcuttur. SuEXEC ile ilgili hata bildiriminde bulunmadan önce bunlara bir göz atmalısınız.

  • suEXEC ile ilgili önemli noktalar
  • Hiyerarşik sınırlamalar

    Güvenlik ve verimlilik adına, tüm suEXEC isteklerinin sanal konaklar için üst düzey belge kökünün altındaki dosyalarla, kullanıcı dizinleri için ise üst düzey bireysel belge köklerinin altındaki dosyalarla sınırlı kalması gerekir. Örneğin, dört sanal konağınız varsa ve suEXEC çalıştırıcısının getirilerinden faydalanmak istiyorsanız, sanal konaklarınızın belge kök dizinlerini ana sunucunun belge kök dizininin altında kalacak şekilde yapılandırmanız gerekir (örnek yolda).

  • SuEXEC'in PATH ortam değişkeni

    Bunu değiştirmek tehlikeli olabilir. Bu değişkende tanımladığınız her yolun güvenli bir dizini işaret ettiğinden emin olmalısınız. Başkalarının oralarda bir truva atı çalıştırmasını istemiyorsanız buna çok dikkat ediniz.

  • SuEXEC kodunda değişiklik

    Gerçekte ne yaptığınızı bilmiyorsanız bu, büyük bir sorun olabilir. Böyle şeyler yapmaktan mümkün olduğunca uzak durmalısınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache HTTP Sunucusu ve DNS ile ilgili Konular - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache HTTP Sunucusu ve DNS ile ilgili Konular

Bu sayfanın konusu şöyle özetlenebilirdi: Yapılandırma dosyalarınızda DNS sorguları yapılmasını gerektirecek ayarlamalardan kaçınınız. Eğer yapılandırma dosyalarınızda DNS sorgusu yapılarak çözümlenebilecek adresler bulunursa sunucunuz beklenmedik davranışlar (hiç başlamayabilir) gösterebileceği gibi hizmet reddi veya hizmet hırsızlığı (bazı sanal konakların diğerlerine giden sayfaları çalma olasılığı dahil) saldırılarına açık hale gelebilir.

Basit Bir Örnek

# Bu yetersiz bir yapılandırma örneğidir, sunucunuzda kullanmayın.
<VirtualHost falan.fesmekan.dom>
  ServerAdmin filanca@fesmekan.dom
  DocumentRoot "/siteler/fesmekan"
</VirtualHost>

httpd’nin beklendiği gibi işlemesi için her sanal konak için iki veriye mutlaka ihtiyacı vardır: ServerName ve sunucunun bağlantı kabul edip hizmet sunacağı en az bir IP adresi. Yukarıdaki örnekte IP adresi bulunmamaktadır, dolayısıyla Apache, falan.fesmekan.dom adresi için bir DNS sorgusu yapmak zorundadır. Eğer sunucu, yapılandırma dosyasını çözümlediği sırada bir sebeple DNS sunucusuna erişemezse bu sanal konak yapılandırılmayacak ve bu sanal konağa yapılan isteklere yanıt verilemeyecektir.

falan.fesmekan.dom’un 192.168.2.1 IP adresine sahip olduğunu varsayarsak yapılandırma şöyle olurdu:

# Bu yetersiz bir yapılandırma örneğidir, sunucunuzda kullanmayın.
<VirtualHost 192.168.2.1>
  ServerAdmin filanca@fesmekan.dom
  DocumentRoot "/siteler/fesmekan"
</VirtualHost>

Ancak, bu sefer de bu sanal konağın sunucu ismini öğrenmek için httpd’nin bir ters DNS sorgusu yapması gerekecektir. Eğer bu sorgu başarısız olursa kısmi bir yapılandırmaya gidilir. Eğer sanal konak isme dayalı ise sanal konak kısmen bile yapılandırılmaz. IP’ye dayalı sanal konaklar büyük oranda çalışır, fakat (örneğin, bir Redirect varlığında olduğu gibi) sunucu ismini içeren tam bir adres üretilmesini gerektiren bir durumda, sunucu geçerli bir adres üretemez.

Her iki sorunu da çözen yapılandırma şöyle olurdu:

<VirtualHost 192.168.2.1>
  ServerName falan.fesmekan.dom
  ServerAdmin filanca@fesmekan.dom
  DocumentRoot "/siteler/fesmekan"
</VirtualHost>

Hizmet Reddi

Şöyle bir yapılandırmanız olsun:

<VirtualHost falan.fesmekan.dom>
  ServerAdmin filanca@fesmekan.dom
  DocumentRoot "/siteler/fesmekan"
</VirtualHost>

<VirtualHost misal.mesela.dom>
  ServerAdmin falanca@mesela.dom
  DocumentRoot "/siteler/mesela"
</VirtualHost>

falan.fesmekan.dom’a 192.168.2.1, misal.mesela.dom’a 192.168.2.2 atadığınızı fakat, mesela.dom’un DNS kaydının sizin denetiminizde olmadığını varsayalım. Bu yapılandırmayla, mesela.dom’u fesmekan.dom’a giden tüm trafiği çalabilecek duruma getirirsiniz. Bunu gerçekleştirmek için DNS kaydında misal.mesela.dom’a 192.168.2.1 adresinin atanması yeterlidir. Kendi DNS’lerine sahip olduklarından dolayı misal.mesela.dom’a istedikleri IP adresini atamaktan onları alıkoyamazsınız.

192.168.2.1’e gelen isteklerin hepsine (http://falan.fesmekan.dom/biryer şeklinde yazılan adresler dahil) mesela.dom sanal konağınca hizmet sunulacaktır. Apache’nin gelen istekleri sunduğu sanal konaklarla nasıl eşleştirdiğini bilirseniz bunun sebebini kolayca anlarsınız. Bunu kabataslak açıklayan bir belgemiz mevcuttur.

"Ana Sunucu" Adresi

İsme dayalı sanal konak desteği, httpd’nin çalıştığı makinenin IP adres(ler)ini de bilmesini gerektirir. Bu adresi elde etmek için sunucu, ya sunucu genelinde geçerli ServerName yönergesine bakar ya da bir C işlevi olan gethostname’i kullanır (işlev, komut isteminden hostname komutuna dönen yanıtın aynısını döndürür) ve ardından bu adresle ilgili olarak bir DNS sorgusu yapar. Bu sorgudan kaçınmanın henüz bir yolu yoktur.

Eğer bu sorgunun (DNS sunucusunun çökmüş olması gibi bir nedenle) başarısız olabileceğinden korkuyorsanız, makine ismini ve IP adresini /etc/hosts dosyanıza yazabilirsiniz (Makinenizin düzgün olarak açılabilmesi için zaten bu kaydı yapmış olmanız gerekir). Kullandığınız işletim sistemine bağlı olarak bu kaydın /etc/resolv.conf veya /etc/nsswitch.conf dosyasında bulunması gerekebilir.

Herhangi bir nedenle sunucunuz bir DNS sorgusu yapmıyorsa veya yapmamalıysa, httpd’yi HOSTRESORDER ortam değişkenine "local" değerini atadıktan sonra çalıştırabilirsiniz. Bu tamamen işletim sistemine ve kullandığınız çözümleyici kütüphanelere bağlıdır. Ayrıca, ortamı denetlemek için mod_env kullanmıyorsanız, CGI’ler de bundan etkilenir. En iyisi işletim sisteminizin SSS belgelerini ve kılavuz sayfalarını okumaktır.

Bu Sorunlardan Kaçınmak için İpuçları

  • VirtualHost yönergelerinizde IP adresleri kullanınız.
  • Listen yönergelerinizde IP adresleri kullanınız.
  • Tüm sanal konakların ayrı birer ServerName yönergesi olsun.
  • Hiçbir sayfa sunulmayan bir <VirtualHost _default_:*> sanal konağınız olsun.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache Sanal Konak Belgeleri - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache Sanal Konak Belgeleri

Sanal Konak (Virtual Host) terimi tek bir makine üzerinde birden fazla sitenin (sirket1.example.com, sirket2.example.com gibi) barındırılma uygulamasını betimler. Sanal konaklar, "IP’ye dayalı" veya "isme dayalı" olabilir; birincisinde, her site ayrı bir IP adresinden sunulurken, ikincisinde her IP adresinde birden fazla site sunulur. Olayda aynı fiziksel sunucu kullanıldığı halde bu sunucu son kullanıcıya görünür değildir.

Apache yazılımsal olarak IP’ye dayalı sanal konakları destekleyen ilk sunuculardan biridir. 1.1 sürümünden itibaren Apache hem IP’ye dayalı hem de isme dayalı sanal konakları desteklemektedir. İsme dayalı sanal konaklara bazen konağa dayalı sanal konaklar veya IP’ye dayanmayan sanal konaklar da denmektedir.

Aşağıda, Apache HTTP Suncusundaki sanal konak desteğini bütün ayrıntıları ile açıklayan belgeler listelenmiştir.

Ayrıca bakınız:

  • mod_vhost_alias
  • İsme Dayalı Sanal Konaklar
  • IP Adresine Dayalı Sanal Konaklar
  • Sanal Konak Örnekleri
  • Dosya Tanıtıcı Sınırları
  • Kütlesel Sanal Konaklık
  • Ayrıntılı olarak Konak Eşleme

Sanal Konak Desteği

  • İsme Dayalı Sanal Konaklar (Her IP adresinde birden fazla site)
  • IP Adresine Dayalı Sanal Konaklar (Her site için ayrı IP adresi)
  • Çok kullanılan sanal konak yapılandırma örnekleri
  • Dosya Tanıtıcı Sınırları (veya, çok fazla günlük dosyası)
  • Devingen olarak Yapılandırılan Kütlesel Sanal Barındırma
  • Konak Eşlemenin Derinliğine İncelenmesi

Yapılandırma Yönergeleri

  • <VirtualHost>
  • ServerName
  • ServerAlias
  • ServerPath

Sanal konak yapılandırmanız üzerinde hata ayıklamaya çalışıyorsanız Apache’nin -S komut satırı seçeneği şu şekilde çok işinize yarayabilir:

/usr/local/apache2/bin/httpd -S

Bu komut, yapılandırma dosyasının Apache yorumunu dökümler. IP adreslerinin ve sunucu isimlerinin dikkatli bir incelemesi, yapılandırma yanlışlarınızı keşfetmenize yardımcı olabilir. (Diğer komut satırı seçenekleri için httpd programının belgelerine bakınız.)

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


İsme Dayalı Sanal Konaklar - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

İsme Dayalı Sanal Konaklar

Bu belgede isme dayalı sanal konakların ne zaman, nasıl kullanılacakları açıklanmıştır.

Ayrıca bakınız:

  • IP Adresine Dayalı Sanal Konaklar
  • Konak Eşlemenin Derinliğine İncelenmesi
  • Devingen olarak Yapılandırılan Kütlesel Sanal Barındırma
  • Çok kullanılan sanal konak yapılandırma örnekleri

İsme dayalı ve IP’ye dayalı Sanal Konaklar

IP’ye dayalı sanal konaklarda sunulacak sanal konağı doğru tespit edebilmek için bağlantının yapıldığı IP adresine bakılır. Bu bakımdan her konak için ayrı bir IP adresine gereksinim vardır.

İsme dayalı sanal konaklarda ise sunucu, istemcinin HTTP başlığının bir parçası olarak gönderdiği konak adını kullanır. Bu teknikte aynı IP adresini çok sayıda farklı konak kullanabilir.

İsme dayalı sanal barındırma nispeten daha kolaydır, çünkü her konak ismini doğru IP adresiyle eşlemek için DNS sunucunuzu yapılandırdıktan sonra Apache HTTP sunucusunu farklı konak isimlerini tanıyacak şekilde yapılandırmanız yeterli olur. İsme dayalı sanal barındırma ayrıca zaten kıt olan IP adreslerine talebi de azaltır. Bu nedenle, IP’ye dayalı sanal konakları kullanmanızı gerektiren donanım kullanmadıkça isme dayalı sanal konaklar kullanmalısınız. İstemci uyumuna bağlı IP’ye dayalı sanal barındırma için eskiden varolan sebepler genel amaçlı bir HTTP sunucusu için artık uygulanabilir değildir.

İsme dayalı sanal barındırma, IP'ye dayalı sanal barındırma seçim algoritmasını kullanmaz, yani uygun sunucu ismini arama işlemi sadece en iyi IP'ye dayalı adrese sahip sanal konaklar arasında gerçekleşir.

Sunucu isme dayalı sanal konaklardan uygun olanını nasıl seçer

İsme dayalı sanal konak çözümlemesinin ilk adımının IP'ye dayalı çözümleme olduğunun anlaşılması çok önemlidir. İsme dayalı sanal konak çözümlemesi en uygun isme dayalı sanal konağı seçerken önce en iyi IP'ye dayalı eşleşme adaylarının sayısını azaltır, sonra bunlar arasından en uygununu seçer. Tüm VirtualHost yönergelerinde IP adresi yerine joker kullanımı bu IP'ye dayalı eşlemeyi yersiz kılar.

Bir istek geldiğinde, sunucu, istekte kullanılan IP adresi ve portu ile en iyi eşleşen <VirtualHost> bileşenini bulur. Bu IP adresi ve port çifti ile eşleşen birden fazla sanal konak varsa, Apache httpd istekte kullanılan sunucu ismini ServerName ve ServerAlias yönergelerindeki isimlerle karşılaştırır.

Herhangi bir isme dayalı sanal konakta ServerName yönergesini kullanmazsanız, sunucu bu yönergeye sistem konak adından türetilmiş tam nitelenmiş alan adının (FQDN) tanımlandığını varsayacaktır. Bu örtük atama sezgiselliğin istenmediği bir sanal konak eşleşmesi ile sonuçlanabilir ve bu önerilmez.

Bir IP adresi ve port çifti için öntanımlı isme dayalı sankon

ServerName ve ServerAlias yönergelerinde bir eşleşme bulunamazsa, Apache httpd bu çift ile eşleşen sanal konaklar listesindeki ilk sanal konağı kullanır.

İsme Dayalı Sanal Konakların Kullanımı

İlgili Modüller İlgili Yönergeler
  • core
  • DocumentRoot
  • ServerAlias
  • ServerName
  • <VirtualHost>

İlk adım sunacağınız her konak için ayrı bir <VirtualHost> bölümü oluşturmaktır. Her <VirtualHost> bölümü içinde sunulan konağı belirtmek üzere en azından bir adet ServerName yönergesine ve konak içeriğinin dosya sisteminde bulunduğu yeri gösteren bir DocumentRoot yönergesine ihtiyacınız olacaktır.

Ana konağı unutmayın

Mevcut <VirtualHost> yönergelerinin hiçbiriyle eşleşmeyen bir istek için, sunucu veya konak ismine bakılmaksızın genel sunucu yapılandırmanız kullanılır.

Mevcut sitenize isme dayalı bir sanal konak eklerseniz ve bu sanal konak ana sunucunun IP adresi ve portuna sahipse, ana sunucuya yapılan istekler için bu sanal konak kullanılır. Bu bakımdan, ServerName yönergesi ana sunucununki ile aynı olan bir öntanımlı sanal konak oluşturmak akıllıca olacaktır. Aynı arayüz ve portu kullanan fakat farklı yapılandırmalara sahip diğer alan isimlerinin sanal konakları (yani öntanımlı olmayanlar) bu öntanımlı sanal konağın sonrasına yerleştirilmelidir.

ServerName miras alma

İsme dayalı her sanal konak için daima bir ServerName belirtmek en iyisidir.

Eğer bir VirtualHost bölümü içinde bir ServerName belirtilmezse, sunucu ismi olarak ana sunucu yapılandırmasındaki isim kullanılır. Orada da bir sunucu ismi belirtilmemişse, başlatma sırasında dinlenen ilk IP adresinden ters DNS araması ile elde edilen isim kullanılır. Her iki durumda da miras alınan isim gereksiz yere isme dayalı sanal konak ismi haline gelecektir; bu bakımdan isme dayalı her sanal konak için daima bir ServerName belirtmek en iyisidir.

Örnek olarak, site1.example.com adresinden sitenizi sunmakta olduğunuzu ve bunun yanına aynı IP adresini kullanan site2.example.com sanal konağını eklemek istediğinizi varsayalım. Bunun için httpd.conf dosyanıza basitçe şu satırları ekleyebilirsiniz:

<VirtualHost *:80>
    #İlk sanal konak aynı zamanda *:80 için de öntanımlıdır.
    ServerName site1.example.com
    ServerAlias example.com
    DocumentRoot "/siteler/site1"
</VirtualHost>

<VirtualHost *:80>
    ServerName site2.example.com
    DocumentRoot "/siteler/site2"
</VirtualHost>

İsterseniz, <VirtualHost> yönergesinde argüman olarak * yerine doğrudan bir IP adresi belirtebilirsiniz. Hatta, daha sonra, isme dayalı sanal konakları bir IP adresinden ve IP’ye dayalı olanları veya isme dayalı diğer bir sanal konak grubunu diğer IP adreslerinden sunmak isteyebilirsiniz.

Çoğu sunucunun birden fazla isim ile erişilebilir olması istenir. Bu, <VirtualHost> bölümü içine bir ServerAlias yönergesi yerleştirmek suretiyle mümkün olur. Örneğin yukarıdaki örnekte, kullanıcıların aynı siteye farklı isimlerle erişmelerini mümkün kılmak için bölüm içine şu satırı ekleyebilirsiniz:

ServerAlias example.com *.example.com

Böylece example.com alanındaki tüm konaklar için gelen isteklere www.example.com sanal konağından hizmet sunulmuş olur. Konak isimleriyle eşleşmek üzere dosya ismi kalıp karakterleri * ve ? kullanılabilir. Şüphesiz bu isimleri sırf ServerName veya ServerAlias yönergesinde belirtmiş olmakla bu isimleri erişilebilir kılamazsınız. Öncelikle, bu isimleri sunucunuzdaki IP adresleriyle eşlemek üzere yapılandıracağınız bir DNS sunucunuz olmalıdır.

İsme dayalı sanal konaklardan en iyi eşleşme kümesinde olanlar yapılandırmada göründükleri sıraya göre işleme sokulur. Joker kullanımları arasında fark gözetilmeksizin ServerName veya ServerAlias yönergesi eşleşen ilk sanal konak kullanılır.

VirtualHost içindeki isimlerin sırası (jokersiz) bir ServerAlias gibi ele alınır (fakat hiçbir ServerAlias yönergesi ile geçersiz kılınmaz).

Son olarak, sanal konak yapılandırmanıza, <VirtualHost> bölümlerinin içine başka yönergeler yerleştirerek ince ayar çekebilirsiniz. Çoğu yönerge bu bölümlere yerleştirilebilir ve sadece o sanal konakla ilgili yapılandırmayı değiştirmek için kullanılabilir. Belli bir yönergenin sanal konak bölümlerinde kullanılıp kullanılmayacağını yönergenin açıklamasında Bağlam satırına bakarak öğrenebilirsiniz. Ana sunucu bağlamındaki (<VirtualHost> bölümleri dışındaki) yapılandırma yönergelerinden sadece sanal konak bölümlerinde geçersiz kılınmamış olanlar kullanılacaktır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


IP’ye Dayalı Sanal Konak Desteği - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

IP’ye Dayalı Sanal Konak Desteği

Ayrıca bakınız:

  • İsme Dayalı Sanal Konak Desteği

IP'ye dayalı sanal konak desteği nedir

IP'ye dayalı sanal konak desteği, bir isteğin alındığı IP adresi ve porta bağlı olarak farklı yönergeleri uygulamak için bir yoldur. Özetle, farklı siteleri farklı portlardan ve arayüzlerden sunmakta kullanılır.

Çoğu durumda, isme dayalı sanal konaklar birçok sanal konağın tek bir IP adresi/port çiftini paylaşmasını sağladığından daha kullanışlıdır. Neyi kullanacağınıza karar vermek için İsme dayalı ve IP’ye dayalı Sanal Konaklar bölümüne bakınız.

Sistem gereksinimleri

IP’ye dayalı deyince, sunucunun her IP’ye dayalı sanal konak için ayrı bir IP adresi/port çiftine sahip olduğunu anlıyoruz. Bunun olması için, makine ya çok sayıda ağ bağlantısına sahiptir ya da makinede, günümüzde çoğu işletim sistemi tarafından desteklenen sanal arabirimler ve/veya çok sayıda port kullanılıyordur. (Sanal arabirimlerle ilgili ayrıntılar için sistem belgelerinize bakınız; bu konu genellikle IP rumuzları (ip aliases) olarak geçer ve ayarlamak için genellikle "ifconfig" komutu kullanılır.)

Apache HTTP Sunucusu terminolojisinde, tek bir IP adresinin çok sayıda TCP portuyla kullanımı IP'ye dayalı sanal konak desteği olarak bilinir.

Apache nasıl ayarlanır?

Çok sayıda konağı desteklemek üzere Apache iki şekilde yapılandırılabilir. Ya her konak için ayrı bir httpd süreci çalıştırırsınız ya da tüm sanal konakları destekleyen tek bir süreciniz olur.

Çok sayıda süreç kullanıyorsanız:

  • Güvenli bölgeler oluşturmanız gerekiyordur. Örneğin, şirket2’deki hiç kimse dosya sistemi üzerinden şirket1’e ait verileri okuyamasın, sadece herkes gibi tarayıcı kullanarak okuyabilsin istenebilir. Bu durumda, User, Group, Listen ve ServerRoot yönergeleri farklı değerlerle yapılandırılmış iki ayrı süreç çalıştırmanız gerekir.
  • Makine üzerindeki her IP adresini dinlemek için gereken dosya tanıtıcı ve bellek miktarını makul bir seviyede tutabilirsiniz. Bu sadece belli adresleri dinleyerek veya çok sayıda adresle eşleşen adres kalıpları kullanarak mümükün olabilir. Zaten, bir sebeple belli bir adresi dinleme ihtiyacı duyarsanız, diğer tüm adresleri de ayrı ayrı dinlemeniz gerekir. (Bir httpd programı N-1 adresi dinlerken diğerleri kalan adresleri dinleyebilir.)

Tek bir süreç kullanıyorsanız:

  • httpd yapılandırmasının sanal konaklar arasında paylaşılmasına izin veriliyor demektir.
  • Makine çok büyük miktarda isteği karşılayabilir ve ayrı ayrı süreçlerin çalışmasından kaynaklanan önemli başarım kayıpları yaşanmaz.

Çok sayıda sürecin yapılandırılması

Her sanal konak için ayrı bir httpd yapılandırması oluşturulur. Her yapılandırmada, o süreç tarafından sunulacak IP adresi (veya sanal konak) için Listen yönergesi kullanılır. Örnek:

Listen 192.0.2.100:80

Burada konak ismi yerine IP adresi kullanmanız önerilir (ayrıntılar için DNS ile ilgili konular belgesine bakınız).

Sanal konaklar tek bir sürecin yapılandırılması

Bu durum için, ana sunucu ve sanal konakların tümüne gelen istekler tek bir httpd süreci tarafından karşılanır. Yapılandırma dosyasında, her sanal konak için, farklı değerlere sahip ServerAdmin, ServerName, DocumentRoot, ErrorLogveTransferLog veya CustomLog yönergeleri içeren ayrı birer VirtualHost bölümü oluşturulur. Örnek:

<VirtualHost 192.168.1.10:80>
    ServerAdmin bilgi@example.com
    DocumentRoot "/siteler/belgeler/ecom"
    ServerName example.com
    ErrorLog "/siteler/gunlukler/ecom/hatalar.log"
    CustomLog "/siteler/gunlukler/ecom/erisim.log" combined
</VirtualHost>

<VirtualHost 192.168.1.20:80>
    ServerAdmin bilgi@example.org
    DocumentRoot "/siteler/belgeler/eorg"
    ServerName example.org
    ErrorLog "/siteler/gunlukler/eorg/hatalar.log"
    CustomLog "/siteler/gunlukler/eorg/erisim.log" combined
</VirtualHost>

<VirtualHost> yönergesinde konak ismi yerine IP adresi kullanmanız önerilir (ayrıntılar için DNS ile ilgili konular belgesine bakınız).

Belli bir IP adresi veya port kullanımı bunların joker eşdeğerlerine göre daha yüksek öncelik sağlar ve eşleşen bir sanal konak da genel sunucuya göre öncelik alır.

Süreç oluşturmayı denetleyen yönergeler ve bir kaç başka yönerge dışında hemen hemen tüm yapılandırma yönergeleri VirtualHost bölümleri içinde kullanılabilir. Bir yönergenin VirtualHost bölümlerinde kullanılıp kullanılmayacağını öğrenmek için yönerge dizinini kullanarak yönergenin Bağlam’ına bakınız.

suEXEC sarmalayıcısı kullanıldığı takdirde SuexecUserGroup yönergesi de bir VirtualHost bölümü içinde kullanılabilir.

GÜVENLİK:Günlük dosyalarının yazılacağı yeri belirlerken, Apache’yi başlatan kullanıcıdan başka kimsenin yazamayacağı bir yerin seçilmesi bazı güvenlik risklerini ortadan kaldırmak bakımından önemlidir. Ayrıntılar için güvenlik ipuçları belgesine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Devingen olarak Yapılandırılan Kitlesel Sanal Barındırma - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

Devingen olarak Yapılandırılan Kitlesel Sanal Barındırma

Bu belgede sanal konakların sonu belirsiz bir şekilde artışı karşısında Apache HTTP Sunucusunun nasıl daha verimli kullanılacağı açıklanmıştır. Devingen kitlesel konakları oluşturmak için mod_rewrite modülünün kullanımını açıklayan ayrı bir belge de mevcuttur.

Amaç

Burada açıklanan teknikler, httpd.conf dosyanızın örnekteki gibi, aslında hemen hemen birbirinin aynı çok sayıda <VirtualHost> bölümü içereceği zaman yapılacaklar ile ilgilidir.

<VirtualHost 111.22.33.44>
    ServerName                 musteri-1.example.com
    DocumentRoot        "/siteler/musteri-1/belgeler"
    ScriptAlias  "/cgi-bin/"  "/siteler/musteri-1/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.44>
    ServerName                 musteri-2.example.com
    DocumentRoot        "/siteler/musteri-2/belgeler"
    ScriptAlias   "/cgi-bin/"   "/siteler/musteri-2/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.44>
    ServerName                 musteri-N.example.com
    DocumentRoot          "/siteler/musteri-N/belgeler"
    ScriptAlias   "/cgi-bin/"  "/siteler/musteri-N/cgi-bin"
</VirtualHost>

İsteğimiz çok sayıda <VirtualHost> bölümünü devingen olarak çalışan tek bir <VirtualHost> bölümüyle değiştirmektir. Bunun elbette bazı getirileri olacaktır:

  1. Yapılandırma dosyanız küçüleceği için Apache daha çabuk başlatılabilecek ve daha az bellek harcayacaktır. Muhtemelen daha da önemlisi, küçülmüş bir yapılandırmanın bakımı da kolaylaşacağı için hatalar da azalacaktır.
  2. Yeni sanal konakların eklenmesi, DNS’de yeni girdiler oluşturmak ve dosya sisteminde bununla ilgili dizinleri açmak dışında biraz daha basit olacaktır; en azından Apache’yi yeniden yapılandırmak ve yeniden başlatmak zorunda kalmayacaksınız.

Ana götürüsü ise her sanal konak için ayrı birer günlük dosyasına sahip olamayacak olmanızdır. Öte yandan, dosya tanıtıcılarının sınırlı olması nedeniyle bunu yapmayı zaten istemezsiniz. Günlük kayıtları için bir fifo veya bir boru hattı oluşturmak ve diğer uçta çalışan bir süreç vasıtasıyla günlükleri müşterilere paylaştırmak daha iyidir. Böyle bir işlemle ilgili bir örneği split-logfile aracının belgesinde bulabilirsiniz.

Genel Bakış

Bir sanal konak iki bilgiye bakarak belirlenir: IP adresi ve HTTP isteğindeki Host: başlığının içeriği. Devingen sanal barındırma tekniği, isteği yerine getirmek için kullanılacak dosya yoluna bu bilgiyi kendiliğinden girmek esasına dayanır. Bu, Apache httpd ile mod_vhost_alias modülünü kullanarak oldukça kolay yapılabileceği gibi mod_rewrite modülü de kullanılabilir.

Bu modüllerin her ikisi de öntanımlı olarak devre dışıdır. Bu tekniği kullanmak isterseniz Apache httpd'yi yeniden yapılandırıp derleyerek bu iki modülü etkin duruma getirmeniz gerekir.

Devingen sanal konağı normal bir sanal konak gibi göstermek için bazı bilgileri istekten saptamak gerekir. Bunlardan en önemlisi, httpd tarafından göreli URL’lerden normal URL’leri ve benzerlerini üretmek için kullanılan sunucu ismidir. Sunucu ismi ServerName yönergesi ile yapılandırılır ve CGI’ler tarafından SERVER_NAME ortam değişkeni üzerinden kullanılır. Çalışma anındaki asıl değer UseCanonicalName yönergesi tarafından denetlenir. UseCanonicalName Off olduğunda sunucu ismi isteğin Host: başlık alanından elde edilir. UseCanonicalName DNS belirtilmişse, sunucu ismi, sanal konağın IP adresinden tersine DNS sorgusu yapılarak elde edilir. Birincisi isme dayalı sanal konaklar tarafından ikincisi ise IP’ye dayalı sanal konaklar tarafından kullanılır. Eğer httpd, istekte Host: başlığının olmayışı veya DNS sorgusunun başarısız olması sebebiyle sunucu ismini elde edemezse son çare olarak ServerName yönergesinde yazılı değeri kullanır.

Saptanan bilgilerden biri de DocumentRoot yönergesi ile yapılandırılan belge kök dizini olup CGI’ler tarafından DOCUMENT_ROOT ortam değişkeni üzerinden kullanılır. Normal yapılandırmada core modülü tarafından dosya isimlerini URI’lere eşlerken kullanılır. Fakat sunucu devingen sanal konakları kullanmak üzere yapılandırıldığında, eşleştirmeyi farklı yollardan yapan başka bir modül devreye girer (mod_vhost_alias veya mod_rewrite). DOCUMENT_ROOT ortam değişkenine değerini atamaktan sorumlu olan bu iki modülden biri kullanılmazsa CGI veya SSI belgeleri yanlış değerlerle üretilirler.

mod_vhost_alias ile Kitlesel Sanal Konaklar

Yukarıda Amaç bölümünde özetlenen sanal konak düzenlemesinin mod_vhost_alias kullanarak gerçekleştirilmiş halini içeren httpd.conf bölümü aşağıdadır.

# sunucu ismini Host: başlığından elde edelim
UseCanonicalName Off

# Bu günlükleme biçiminde split-logfile aracı kullanılarak
# sanal konak günlükleri ilk alana göre ayrıştırılabilir
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log vcommon"

# istekleri yerine getirmek için kullanılacak
# dosya isimlerine sunucu ismini ekleyelim
VirtualDocumentRoot "/siteler/%0/belgeler"
VirtualScriptAlias  "/siteler/%0/cgi-bin"

Bu yapılandırmayı IP’ye dayalı sanal konaklar için kullanmak isterseniz UseCanonicalName Off yerine UseCanonicalName DNS yazmanız yeterlidir. Böylece dosya ismine eklenecek konak ismi sanal konağın IP adresinden türetilir. %0 değişkeni, Host: başlığı ile belirlenen istekteki sunucu isminin ifadesidir.

Kullanım örnekleri için mod_vhost_aliasmodülünün belgesine bakınız.

Basitleştirilmiş Kitlesel Sanal Konaklar

Bu sistem, yukarıdaki yapılandırmanın bir ISS’nin sunucusuna uyarlanmasından başka bir şey değildir. %2 değişkenini kullanarak, dosya isminde kullanmak üzere sunucu isminin alt dizgelerini seçebiliriz, böylece, örneğin www.user.example.com belgeleri /home/user/www dizininde bulunabilir. Farklı olarak her sanal konak için bir tane değil hepsi için bir tane cgi-bin olacaktır.

UseCanonicalName Off

LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

# sunucu ismini içerecek dosya isimlerini oluşturalım
VirtualDocumentRoot "/home/%2/www"

# ortak cgi-bin dizini
ScriptAlias  "/cgi-bin/"  "/siteler/std-cgi/"

mod_vhost_alias belgesinde daha karmaşık VirtualDocumentRoot örnekleri vardır.

Aynı Sunucuda Kişisel ve Kurumsal Sanal Konaklar

Daha karmaşık ayarlamalar yaparak httpd’nin normal <VirtualHost> bölümlerini farklı kitlesel sanal konak yapılandırmaları için kullanabilirsiniz. Örneğin, bireysel müşterileriniz için bir IP adresiniz, kurumsal müşterileriniz için de başka bir IP adresiniz olsun. Her biri için ayrı ayrı sanal konaklar ayarlamak yerine aşağıdaki gibi bir yapılandırma kullanabilirsiniz:

UseCanonicalName Off

LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon

<Directory "/siteler/kurumsal">
    Options FollowSymLinks
    AllowOverride All
</Directory>

<Directory "/siteler/bireysel">
    Options FollowSymLinks
    AllowOverride None
</Directory>

<VirtualHost 111.22.33.44>
    ServerName kurumsal.example.com

    CustomLog "logs/access_log.kurumsal" vcommon

    VirtualDocumentRoot "/siteler/kurumsal/%0/belgeler"
    VirtualScriptAlias  "/siteler/kurumsal/%0/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.45>
    ServerName bireysel.example.com

    CustomLog "logs/access_log.bireysel" vcommon

    VirtualDocumentRoot "/siteler/bireysel/%0/belgeler"
    ScriptAlias         "/cgi-bin/" "/siteler/std-cgi/"
</VirtualHost>

Bilginize

Eğer ilk <VirtualHost> bölümü bir ServerName yönergesi içermezse ilgili IP için ters DNS sorgusu yapılır. Eğer sorgudan elde edilen isim sunucunun ismi değilse bu istenmeyen duruma bir çözüm olarak bir bilgilendirme bölümü (örn, ServerName bilgi.example.com) eklenebilir.

IP’ye dayalı sanal konakları daha verimli kılmak

İlk örnekte IP’ye dayalı sanal konaklar için kullanılmak istenirse yapılandırmada neyin nasıl değiştirileceği belirtilmişti. Her istek için ayrı bir DNS sorgusu gerekeceğinden bu başarım düşmesine yol açar. DNS sorgusu ihtiyacını ortadan kaldırmak için, bir çözüm olarak dosya sistemi, konak isimleri yerine IP adreslerine göre düzenlenebilir. Günlük kayıtları da IP adreslerine göre ayrıştırılacak şekilde ayarlanabilir.

# Sunucu ismini IP adresinden ters DNS sorgusu ile elde edelim
UseCanonicalName DNS

# Günlük kayıtları IP adreslerine göre ayrıştırılabilsin
LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

# dosya isimleri IP adreslerini içersin
VirtualDocumentRootIP "/siteler/%0/belgeler"
VirtualScriptAliasIP  "/siteler/%0/cgi-bin"

mod_rewrite ile Kitlesel Sanal Konaklar

Kitlesel sanal barındırma mod_rewrite modülü kullanarak da gerçeklenebilir. Ya basitçe RewriteRule yönergelerini kullanırsınız ya da daha karmaşık olarak sanal konak tanımlarınızı harici bir yerde tutar ve bunlara RewriteMap yönergesini kullanarak erişirsiniz. Bu teknikler ayrıntılı olarak rewrite belgelerinde açıklanmıştır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Sanal Konak Örnekleri - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

Sanal Konak Örnekleri

Bu belgede sanal konaklarla ile ilgili olarak karşılaşılması olası tüm senaryolara yer verilmeye çalışılmıştır. Buradaki senaryolar, tek bir sunucu üzerinde isme dayalı veya IP’ye dayalı sanal konaklar aracılığıyla çok sayıda sitenin sunumu ile ilgilidir.

Tek bir IP ile çok sayıda isme dayalı site

Bu örnekte, makinenizin tek bir IP adresine sahip olduğunu ve bu makineye example.com ve example.org şeklinde (DNS A kayıtları sayesinde) farklı isimlerle erişilebildiğini varsayalım.

Bilginize

Apache sunucusu üzerinde sanal konakları yapılandırmakla bu konak isimleri için sihirli bir şekilde DNS kayıtlarının da oluşturulmasını sağlamış olmazsınız. Bu isimler için ilgili DNS kayıtlarında sizin IP adresinize çözümlenen A kayıtlarının olması gerekir, yoksa sitenize kimse erişemez. Sitelere erişimi yerel olarak denemek isterseniz, bu girdileri hosts dosyanıza yazabilirsiniz. Fakat bu sadece sizin makinenizde çalışır. Yerel ağınızdaki her makinenin hosts dosyasına bu girdileri yazarak yerel ağdan erişimi bu yolla sağlayabilirsiniz ama dış ağdan gelecek ziyaretçileriniz için DNS kayıtlarınızın olması şarttır.

# Apache’nin 80. portu dinlediğinden emin olalım
Listen 80
<VirtualHost *:80>
  DocumentRoot "/siteler/ecom"
  ServerName example.com

  # Diğer yönergeler, burada ...
</VirtualHost>

<VirtualHost *:80>
  DocumentRoot "/siteler/eorg"
  ServerName example.org

  # Diğer yönergeler, burada ...
</VirtualHost>

Yıldız imleri tüm adreslerle eşleşmeyi sağladığından ana sunucu (yapılandırma dosyası genelindeki yapılandırma - sunucu geneli) erişilebilir olmayacaktır. Yapılandırma dosyasındaki ServerName example.com yönergeli konak, ilk sanal konak olduğundan en yüksek önceliğe sahiptir ve öntanımlı veya baskın site olarak davranır. Yani, hiçbir ServerName yönergesi ile eşleşmeyen bir istek alındığında bu istek ilk VirtualHost yapılandırması ile karşılanır.

Bilginize

IP adresi ve porta dayalı ayrımı umursamıyorsanız, * yerine kendi IP adresinizi yazabilirsiniz.

NameVirtualHost 192.168.1.22

<VirtualHost 192.168.1.22>
  # vs. ...
</VirtualHost>

Bununla birlikte, IP adresinin önceden kestirilebilir olmadığı sistemlerde, örneğin, hizmet sağlayıcınıza çevirmeli ağ ile bağlanıyor ve onun rasgele atadığı bir IP adresi için bir devingen DNS çözümü kullanıyorsanız, IP adresi değil de * kullanmak daha çok işinize yarayacaktır. Yıldız imi her IP adresi ile eşleşeceğinden IP adresiniz değişse bile bu yapılandırmayı değiştirmeden kullanabilirsiniz.

Yukarıdaki yapılandırmayı hemen hemen tüm isme dayalı sanal konaklar için kullanabilirsiniz. Bu yapılandırmanın çalışmayacağı tek durum, farklı içerikleri farklı IP adreslerinden sunma gereğiyle karşılaşmaktır.

IP adresleri farklı çok sayıda isme dayalı site

Bilginize

Burada açıklanan teknikler istendiği kadar çok IP adresine genişletilebilir.

Sunucunun iki IP adresi olsun. Birinden "ana sunucu" (192.168.1.2) diğerinden example.com 192.168.2.2 hizmet versin. Bu arada başka sanal konakları da sunabilelim istiyoruz.

Listen 80

# Bu, 192.168.1.2 adresindeki "ana sunucu" olsun
ServerName sunucu.example.com
DocumentRoot "/siteler/anasunucu"

<VirtualHost 192.168.1.20>
    DocumentRoot "/siteler/ecom"
    ServerName example.com

    # Diğer yönergeler, burada ...
</VirtualHost>

<VirtualHost 192.168.1.20>
    DocumentRoot "/siteler/eorg"
    ServerName example.org

    # Diğer yönergeler, burada ...
</VirtualHost>

192.168.1.20 adresinden gelmeyen tüm isteklere ana sunucu (sunucu.example.com), 192.168.1.20 adresinden gelen sunucu ismi belirtmeyenler ile Host: başlığı belirtmeyenlere ise example.com hizmet verecektir.

Aynı içeriği farklı IP adresleriyle sunmak (örn., dahili ve harici ağlara)

Sunucu makine iki IP adresine sahip olsun. Biri iç ağa (192.168.1.1) diğeri dış ağa (172.20.30.40) bakıyor olsun. sunucu.example.com ismi dış ağda dış ağa bakan IP’ye, iç ağda ise iç ağa bakan IP’ye çözümleniyor olsun.

Bu durumda, sunucu hem iç hem de dış ağdan gelen isteklere aynı içerik, dolayısıyla aynı VirtualHost bölümü ile hizmet verebilir.

<VirtualHost 192.168.1.1 172.20.30.40>
    DocumentRoot "/siteler/sunucu"
    ServerName sunucu.example.com
    ServerAlias sunucu
</VirtualHost>

Artık, hem iç hem de dış ağdan gelen isteklere aynı VirtualHost bölümünden hizmet sunulacaktır.

Bilginize:

İç ağdan istek yapan biri, tam nitelenmiş konak ismi sunucu.example.com yerine makine ismini (sunucu) kullanabilir (ServerAlias sunucu satırına dikkat).

Ayrıca, yukarıdaki gibi iki ayrı IP adresi belirtmek yerine sadece * belirtmekle sunucunun tüm IP adreslerine yine aynı içerikle yanıt vereceğine dikkat ediniz.

Farklı portlarla farklı siteler

Aynı IP adresine sahip çok sayıda konak ismine sahip olduğunuzu ve bunların bazılarının farklı portları kullanmasını istediğinizi varsayalım. Aşağıdaki örnekte, isim eşleşmesinin, en iyi eşleşen IP adresi ve port çifti saptandıktan sonra yer alması gösterilmiştir.

Listen 80
Listen 8080

<VirtualHost 172.20.30.40:80>
    ServerName example.com
    DocumentRoot "/siteler/ecom-80"
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    ServerName example.com
    DocumentRoot "/siteler/ecom-8080"
</VirtualHost>

<VirtualHost 172.20.30.40:80>
    ServerName example.org
    DocumentRoot "/siteler/eorg-80"
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    ServerName example.org
    DocumentRoot "/siteler/eorg-8080"
</VirtualHost>

IP’ye dayalı sanal konaklar

Sunucu makinenin, biri example.com adından çözümlenen 172.20.30.40, diğeri example.org adından çözümlenen 172.20.30.50 diye iki IP adresi olsun.

Listen 80

<VirtualHost 172.20.30.40>
    DocumentRoot "/siteler/ecom"
    ServerName example.com
</VirtualHost>

<VirtualHost 172.20.30.50>
    DocumentRoot "/siteler/eorg"
    ServerName example.org
</VirtualHost>

<VirtualHost> yönergelerinde belirtilmeyen adreslerle yapılan isteklere (örneğin, localhost) sunucu genelindeki yapılandırma ile ana sunucu yanıt verecektir.

Hem IP’ye hem de porta dayalı sanal konaklar

Sunucu makinenin, biri example.com adından çözümlenen 172.20.30.40, diğeri example.org adından çözümlenen 172.20.30.50 diye iki IP adresi olsun ve iki konak da hem 80 hem de 8080 portlarında çalışsınlar istiyoruz.

Listen 172.20.30.40:80
Listen 172.20.30.40:8080
Listen 172.20.30.50:80
Listen 172.20.30.50:8080

<VirtualHost 172.20.30.40:80>
    DocumentRoot "/siteler/ecom-80"
    ServerName example.com
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    DocumentRoot "/siteler/ecom-8080"
    ServerName example.com
</VirtualHost>

<VirtualHost 172.20.30.50:80>
    DocumentRoot "/siteler/eorg-80"
    ServerName example.org
</VirtualHost>

<VirtualHost 172.20.30.50:8080>
    DocumentRoot "/siteler/eorg-8080"
    ServerName example.org
</VirtualHost>

Hem isme hem de IP‘ye dayalı sanal konaklar

Bir VirtualHost yönergesinde belirtilen bir IP adresi başka bir sanal konakta görünmüyorsa bu sankon kesinlikle IP'ye dayalı bir sanal konaktır.

Listen 80

<VirtualHost 172.20.30.40>
    DocumentRoot "/siteler/ecom"
    ServerName example.com
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/siteler/eorg"
    ServerName example.org
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/siteler/enet"
    ServerName example.net
</VirtualHost>

# IP'ye dayalı
<VirtualHost 172.20.30.50>
    DocumentRoot "/siteler/eedu"
    ServerName example.edu
</VirtualHost>

<VirtualHost 172.20.30.60>
    DocumentRoot "/siteler/egov"
    ServerName example.gov
</VirtualHost>

Virtualhost ve mod_proxy’nin birlikte kullanımı

Bu örnekte bir arabirimi dışarıya bakan bir makinede, başka bir makinede çalışan bir sunucuya sanal konak olarak, bir vekil sunucu çalıştırmak istediğimizi varsayıyoruz. 192.168.111.2 IP adresli bir makinede aynı isimde bir sanal konak yapılandırılmış olsun. Çok sayıda konak ismi için vekil olarak tek bir makine kullandığımızdan ve konak isminin de aktarılmasını arzuladığımızdan ProxyPreserveHost On yönergesini kullandık.

<VirtualHost *:*>
    ProxyPreserveHost On
    ProxyPass "/" "http://192.168.111.2/"
    ProxyPassReverse "/" "http://192.168.111.2/"
    ServerName konak.example.com
</VirtualHost>

_default_ sanal konakları

Tüm portlar için _default_

Bir IP adresi ve port belirtilmeyen veya hiçbir sanal konağın hiçbir adresi/portu ile eşleşmeyen istekleri yakalamak istersek...

<VirtualHost _default_:*>
    DocumentRoot "/siteler/default"
</VirtualHost>

Bütün portlarla eşleşen böyle bir öntanımlı sanal konağın kullanımı hiçbir isteğin ana sunucuya gitmemesi sonucunu doğurur.

Bir öntanımlı sanal konak, asla, isme dayalı sanal konaklar için kullanılmış bir adrese/porta gönderilmiş bir isteğe hizmet sunmaz. Eğer istek bilinmeyen bir Host: başlığına sahipse veya hiç Host: başlığı içermiyorsa isteğe daima ilk (yapılandırma dosyasındaki ilk) isme dayalı sanal konak hizmet sunar.

Her isteği tek bir bilgilendirme sayfasına (veya betiğe) yönlendirmek isterseniz AliasMatch veya RewriteRule yönergesini kullanabilirsiniz.

Farklı portlardan _default_

Önceki yapılandırmaya ek olarak 80. portta ayrı bir _default_ sanal konağı kullanmak istersek...

<VirtualHost _default_:80>
    DocumentRoot "/siteler/default80"
    # ...
</VirtualHost>

<VirtualHost _default_:*>
    DocumentRoot "/siteler/default"
    # ...
</VirtualHost>

80. porttan hizmet sunan _default_ sanal konağı IP adresi belirtilmeyen tüm istekleri yakalar, bunu yapabilmesi için yapılandırma dosyasında tüm portlara hizmet sunan benzerinden önce yer almalıdır. Bu durumda ana sunucu hiçbir isteğe yanıt vermeyecektir.

Tek portluk _default_

_default_ sanal konağının sadece 80. porttan hizmet sunmasını istersek...

<VirtualHost _default_:80>
    DocumentRoot "/siteler/default"
    ...
</VirtualHost>

80. porttan gelen IP adresi belirtilmemiş isteklere _default_ sanal konağı, diğer portlardan gelen adres belirtilmemiş isteklere ise ana sunucu hizmet verecektir.

Bir sanal konak bildiriminde * kullanımı _default_ kullanımından daha yüksek öncelik sağlar.

Bir isme dayalı sanal konağı bir IP’ye dayalı sanal konakla yansılamak

İsme dayalı sanal konak örneklerinin 2. sinde adı geçen example.org bu örnekte kendi IP adresinden hizmet veriyor olsun. İsme dayalı sanal konağı eski IP adresiyle kaydetmiş vekiller ve isim sunucularından kaynaklanacak olası sorunlardan kaçınmak için yansılama sırasında sanal konağı hem eski hem de yeni IP adresiyle sunmamız lazım.

Çözüm kolay, çünkü yapacağımız sadece VirtualHost yönergesine yeni IP adresini (192.168.1.2) eklemek olacak.

Listen 80
ServerName example.com
DocumentRoot "/siteler/ecom"

<VirtualHost 192.168.1.20 192.168.1.2>
    DocumentRoot "/siteler/eorg"
    ServerName example.org
    # ...
</VirtualHost>

<VirtualHost 192.168.1.20>
    DocumentRoot "/siteler/enet"
    ServerName example.enet
    ServerAlias *.example.enet
    # ...
</VirtualHost>

Böylece sanal konağa hem yeni (bir IP’ye dayalı sanal konak olarak) hem de eski adresinden (bir isme dayalı sanal konak olarak) erişilebilecektir.

ServerPath yönergesinin kullanımı

İsme dayalı iki sanal konağı olan bir sunucumuz olsun. Doğru sanal konağa erişebilmek için istemcinin doğru Host: başlığı göndermesi gerekir. Eski HTTP/1.0 istemcileri böyle bir başlık göndermedikleri için Apache istemcinin hangi sanal konağa erişmek istediğini bilemez (ve isteğe ilk sanal konaktan hizmet sunar). Daha iyi bir geriye uyumluluk sağlamak için isme dayalı sanal konağa bir önek bağlantısı içeren bir bilgilendirme sayfası sunmak üzere yeni bir sanal konak oluşturabiliriz.

<VirtualHost 172.20.30.40>
    # ilk sanal konak
    DocumentRoot "/siteler/baska"
    RewriteEngine On
    RewriteRule "." "/siteler/baska/index.html"
    # ...
</VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /siteler/baska/bir
    ServerName "bir.baska.tld"
    ServerPath "/bir/"
    RewriteEngine On
    RewriteRule "^(/bir/.*) /siteler/baska$1"
    # ...
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/siteler/baska/iki"
    ServerName iki.baska.tld
    ServerPath "/iki/"
    RewriteEngine On
    RewriteRule "^(/iki/.*)" "/siteler/baska$1"
    # ...
</VirtualHost>

ServerPath yönergesinden dolayı http://bir.baska.tld/bir/ şeklinde yapılan isteklere daima “bir” sanal konağı hizmet sunacaktır.

http://bir.baska.tld/ şeklinde yapılan isteklere ise istemcinin doğru Host: başlığı göndermesi şartıyla “bir” sanal konağı hizmet sunacaktır. İstemci, bir Host: başlığı göndermediği takdirde ilk konaktan bir bilgilendirme sayfası alacaktır.

Yalnız buradaki bir tuhaflığa dikkat edin: Eğer istemci bir Host: başlığı göndermeden http://iki.baska.tld/bir/ şeklinde bir istek yaparsa bu isteğe de “bir” sanal konağı hizmet sunacaktır.

RewriteRule yönergesi, bir istemcinin, bir URL öneki belirtsin ya da belirtmesin doğru Host: başlığı gönderdiğinden emin olmak için kullanılmıştır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Sanal Konak Eşlemenin Derinliğine İncelenmesi - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

Sanal Konak Eşlemenin Derinliğine İncelenmesi

Bu belgede, bir istek aldığında Apache’nin hangi sanal konak ile hizmet sunacağına nasıl karar verdiği açıklanmaya çalışılmıştır.

Çoğu kullanıcı hangi türü kullanacağına karar vermek için önce İsme dayalı ve IP’ye dayalı Sanal Konak bölümünü, sonra İsme Dayalı Sanal Konak Desteği veya IP’ye Dayalı Sanal Konak Desteği belgesini okumalı ve bazı örneklere göz atmalıdır.

Bunlardan sonra tüm ayrıntıları anlamak isterseniz tekrar bu sayfaya gelebilirsiniz.

Ayrıca bakınız:

  • IP’ye Dayalı Sanal Konak Desteği
  • İsme Dayalı Sanal Konak Desteği
  • Çok Kullanılan Sanal Konak Örnekleri
  • Devingen olarak Yapılandırılan Kitlesel Sanal Barındırma

Yapılandırma Dosyası

Bu belgede <VirtualHost> bölümleri dışında kalan tanımlardan bahsederken ana_sunucu diyeceğiz.

<VirtualHost> bölümlerindeki tanımlamalardan bahsederken sankonlar diyeceğiz.

Her VirtualHost bölümü en az bir adres ve isteğe bağlı portlar içerir.

Sanal konak tanımlarının içindeki IP adreslerinin yerine konak isimleri kullanılabilir, fakat bunlar başlatma sırasında çözümleneceklerinden çözümlemedeki bir başarısızlık bu sanal konak tanımlarının yoksayılması ile sonuçlanacaktır. Bu bakımdan önerilmez.

VirtualHost yönergesinde görünen her adresin seçimlik bir portu olabilir. Eğer bir port belirtilmemişse, port olarak * belirtilmiş gibi bütün portlar dinlenir.

(VirtualHost yönergesinde belirtilen port numaraları Apache httpd'nin dinleyeceği port numaraları olarak yorumlanmaz, sadece bir isteği işleme sokarken hangi VirtualHost bölümünün seçileceğini belirlerler. Sunucunun dinleyeceği adresleri ve portları belirtmek için Listen yönergesini kullanın.)

Adreslerin tamamını (DNS sorgularındaki çoklu sonuçlar dahil) içeren kümeye sankonların adres kümesi denir.

Apache httpd, bir IP adresi ve port birleşimi için en belirgin eşleşmelerin listelendiği çok sayıdaki sanal konak arasında ayırdedici olarak istemci tarafından sağlanan HTTP Host başlığını kullanır.

ServerName yönergesi sunucu tanımının içinde herhangi bir yerde görünebilirse de her göründüğü yerde bir öncekini iptal eder. Hiç ServerName belirtilmemişse, Apache httpd, sunucu ismini sunucunun IP adresinden saptamaya çalışır.

Belli bir IP adresi ve port çifti için yapılandırma dosyasındaki ilk isme dayalı sankon önemlidir, çünkü başka hiçbir sankonun ServerName veya ServerAlias yönergesi ile eşleşmeyen bu adres ve port çifti için alınmış tüm isteklerde bu sankon kullanılır. Ayrıca, sunucunun Sunucu İsmi Belirtimini desteklemediği durumlarda tüm SSL bağlantıları için bu sankon kullanılır.

VirtualHost içindeki isimlerin sırası (jokersiz) bir ServerAlias gibi ele alınır (fakat hiçbir ServerAlias yönergesi ile geçersiz kılınmaz).

Her sankon için bazı değerler öntanımlı olarak atanır. Bunların başlıcaları:

  1. Sankon bir ServerAdmin yönergesi içermiyorsa, Timeout, KeepAliveTimeout, KeepAlive, MaxKeepAliveRequests, ReceiveBufferSize ve SendBufferSize yönergeleri için öntanımlı değerler ana_sunucudaki eşdeğerlerinden miras alınır. (Yani, bu yönergeler için ana_sunucudaki son değerler miras alınır.)
  2. Sankon için öntanımlı dizin erişim izinlerinin tanımlandığı "arama öntanımlıları" ana_sunucununkilere katılır. Buna her modülün dizinlere özgü yapılandırma bilgileri dahildir.
  3. Her modülün ana_sunucudaki sunuculara özgü yapılandırmaları sankon sunucusununkilerle katıştırılır.

Esasen, ana_sunucu, sankon sunucularını oluştururken bir öntanımlılar listesi veya öntanımlı değerlere dayanak noktası olarak ele alınır. Fakat bu ana_sunucu tanımlarının yapılandırma dosyasındaki yerlerinin saptanmasının konumuzla ilgisi yoktur; ana_sunucu yapılandırmasının tamamı son katıştırma yapılacağı zaman çözümlenir. Bu bakımdan, ana_sunucu tanımlarından bir kısmı sankon tanımlarından sonra yer alsa bile sankon tanımlarında etkili olabilir.

Eğer, bu noktada ana_sunucu hiçbir ServerName satırı içermiyorsa httpd programının çalıştığı makinenin konak ismi öntanımlıdır. Ana_sunucunun ServerName için yaptığı DNS sorgusundan dönen IP adreslerine ana_sunucu adres kümesi diyoruz.

Tanımsız ServerName alanları için bir isme dayalı sankon, sankonu tanımlayan VirtualHost yönergesinde belirtilen ilk adresi öntanımlı değer kabul eder.

Sihirli _default_ sankonları için ana_sunucunun ServerName değeri kullanılır.

Sanal Konağın Belirlenmesi

Sunucu bir istek durumunda hangi sankonun kullanılacağını şöyle belirler:

IP adresi aranır

Bir adres ve port için bağlantı ilk alındığında Apache httpd tüm VirtualHost tanımlarında bu çifti arar.

Arama başarısız olursa * (herşey) eşleşmelerine bakılır.

Bir eşleşme bulunamazsa hizmet ana sunucudan sunulur.

Arama sonucunda bu IP adresi için bulunmuş VirtualHost tanımları varsa sonraki adım hizmetin bir IP’ye dayalı sankondan mı yoksa isme dayalı bir sankondan mı sunulacağına karar vermektir.

IP’ye dayalı sankon

Eğer en iyi eşleşme olarak saptanmış IP adresi ve port çiftini içeren sadece bir VirtualHost yönergesi varsa artık karar vermek için başka bir şey yapmaya gerek yoktur ve istek bu sankondan sunulur.

İsme dayalı sankon

Eğer en iyi eşleşme olarak saptanmış IP adresi ve port çiftini içeren birden fazla VirtualHost yönergesi varsa, sonraki adımlardaki "liste" eşleşen sankonların listesi olup sankonlar listede yapılandırma dosyasındaki yerlerine göre sıralanırlar.

Bağlantı SSL kullanıyorsa, sunucunun Sunucu İsmi Belirtimini desteklediği durumlarda SSL istemci uzlaşımı, istenen konak ismiyle birlikte TLS eklentisini de içeriyorsa, konak ismi, SSL olmayan bağlantılardaki Host: başlığı kullanımına benzer şekilde aşağıdaki gibi kullanılır. Aksi takdirde, SSL bağlantıları için adresin eşleştiği ilk isme dayalı sankon kullanılır. Sunucunun bağlantı için hangi sertifikayı kullanacağını sankon belirlediği için bu önemlidir.

İstek bir Host: başlık alanı içeriyorsa, listede ServerName veya ServerAlias alanı başlık alanı ile eşleşen ilk sankona bakılır. Host: alanı bir port içerebilirse de Apache httpd bunu yoksayarak daima istemcinin isteği gönderdiği portu gerçek port kabul eder.

Yapılandırma dosyasındaki belirtilen IP adresiyle eşleşen ilk sankon en yüksek önceliğe sahiptir ve sunucu ismi bilinmeyen ve (bir HTTP/1.0 isteği gibi) Host: başlık alanı içermeyen istekleri de yakalar.

Kalıcı bağlantılar

Yukarıda açıklanan IP araması belli bir TCP/IP oturumunda bir defaya mahsus yapıldığı halde bir kalıcı/KeepAlive bağlantı sırasında her istek için ayrı bir arama yapılır. Başka bir deyişle, bir istemci tek bir kalıcı bağlantı üzerinde farklı isme dayalı sankonlardan sayfa talebinde bulunabilir.

Mutlak URI

Eğer istekte belirtilen URI bir mutlak URI ise ve istek yapılan konak ismi ve port ana sunucuyla veya sankonlardan biriyle eşleşiyorsa, şema/konakadı/port öneki ayrılır ve elde edilen göreli URI ilgili sankondan veya ana sunucudan sunulur. Eğer bir eşleşme sağlanamazsa URI’ye dokunulmaz ve istek bir vekil isteği olarak ele alınır.

İzlenimler

  • İsme dayalı sanal konak işlemleri, sunucunun en iyi eşleşen IP'ye dayalı sanal konağı seçmesinin ardından uygulanır.
  • İstemcinin hangi IP adresine bağlandığını umursamıyorsanız, sanal konaklarınızda adres olarak "*" kullanın, böylece yapılandırılmış sankonların hepsine isme dayalı sanal konak işlemleri uygulanır.
  • Bir IP’ye dayalı sankon için asla ServerAlias ve ServerPath değerine bakılmaz.
  • Sıralama sadece aynı IP adresine sahip isme dayalı sankonlar arasında önemlidir. Aynı adres kümesine mensup isme dayalı sankonlardan yapılandırma dosyasında ilk sırada yer alanı en yüksek önceliğe sahiptir.
  • Eşleştirme işlemi sırasında Host: başlık alanında belirtilen port asla kullanılmaz. Apache httpd daima istemcinin isteği gönderdiği gerçek portu kullanır.
  • Eğer aynı IP adresine sahip IP’ye dayalı iki sankon varsa, bunlara örtük olarak isme dayalı sanal konak işlemleri uygulanır. 2.3.11 sürümünden beri yeni davranış şekli budur.
  • Ana_sunucunun bir isteğe hizmet sunabilmesi için istemcinin bağlandığı IP adresi ve port hiçbir yerde belirtilmemiş ve hiçbir sankon ile eşleşme sağlanamamış olmalıdır. Başka bir deyişle, istemcinin bağlandığı port ile eşleşen bir _default_ sankon olmadıkça adres ve port belirtmeyen bir isteğe ana_sunucu yanıt verecektir.
  • VirtualHost yönergelerinde asla DNS isimleri belirtmemelisiniz. Aksi takdirde sunucuyu başlatma sırasında DNS sorgusu yapmaya zorlamış olursunuz. Listelenen tüm alanlar için DNS üzerinde tam denetime sahip değilseniz bu ayrıca bir güvenlik tehdidine yol açar. Bu konuda daha ayrıntılı bilgi edinmek için DNS ile ilgili konular ve Apache belgesine bakınız.
  • ServerName her sankon için ayrı ayrı belirlenmiş olmalıdır. Aksi takdirde her sankon için bir DNS sorgusu gerekir.

İpuçları

DNS konuları sayfasındaki ipuçlarına ilaveten burada da bazı ipuçları bulacaksınız:

  • Ana sunucu tanımlarının hepsini VirtualHost tanımlarının öncesinde bitirin. Bu ayrıca yapılandırmanızın okunabilirliğini de arttırır; VirtualHost tanımlarının sonrasına sarkan yapılandırmaların katıştırılması işlemi tüm sanal konakları etkileyebilen tanımlar bakımından bir karışıklığa/belirsizliğe sebep olabilir.)

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Dosya Tanıtıcı Sınırları - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Sanal Konaklar

Dosya Tanıtıcı Sınırları

Çok büyük sayıda sanal konak kullanıyorsanız ve bunların her biri için ayrı günlük kayıtları tutuyorsanız, Apache dosya tanıtıcılarını tüketebilir. Apache tarafından, dahili olarak 10-20 dosya tanıtıcıya ek olarak her hata günlüğü için bir ve her diğer günlük kaydı için bir dosya tanıcı kullanılır. Unix işletim sisteminde dosya tanıtıcıların sayısı süreç başına 64 taneyle sınırlıdır ve gerekirse donanıma bağlı olarak arttırılabilir.

Apache gerektiğinde bu sınırı kendisi arttırmaya çalışırsa da bu her zaman mümkün olmaz. Şöyle ki:

  1. Sisteminiz setrlimit() sistem çağrısını sağlamıyordur.
  2. Sisteminizde setrlimit(RLIMIT_NOFILE) çağrısı hiçbir işe yaramıyordur (örneğin, Solaris 2.3).
  3. Dosya tanıtıcılarının sayısı donanıma bağlı olarak daha fazla arttırılamıyordur.
  4. Sisteminiz dosya tanıtıcı sayısını başka sınırlara bağlı kılmıştır: örneğin stdio akımları ile ilgili sınır, dosya tanıtıcı sayısının 256’nın altında ollmasını gerektiriyordur (Solaris 2).

Böyle sorunlar karşısında yapabilecekleriniz:

  • Ana günlük dosyaları hariç, <VirtualHost> bölümlerinde günlük dosyası belirtmeyerek günlük dosyası sayısını düşürürsünüz. (Bunun nasıl yapılacağını öğrenmek için Günlük kayıtlarının ayrıştırılması bölümüne bakınız.)
  • Sisteminizde serbest dosya tanıtıcı sayısı 1-2 civarına düşerse Apache’yi aşağıdaki gibi bir betikle yeniden çalıştırarak dosya tanıtıcı sayısını arttırabilirsiniz:

    #!/bin/sh
    ulimit -S -n 100
    exec httpd

Günlük kayıtlarının ayrıştırılması

Günlük dosyalarını çok sayıda sanal konak için ortak olarak kullanıyorsanız, sanal konaklar için istatistiksel çözümlemeler yapmak amacıyla sırası geldiğinde bunları ayrıştırabilirsiniz. Bu işlem aşağıda anlatıldığı gibi yapılabilir.

İlk iş olarak, sanal konak bilgilerini günlük girdilerine eklemeniz gerekir. Bu işlem, LogFormat yönergesi ve %v biçem değişkeni ile yapılabilir. Günlük girdisi biçem dizgesinin başına bunu ekleyiniz:

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost
CustomLog logs/multiple_vhost_log vhost

Bu yapılandırma ile her günlük kaydının başında sanal konağın ServerName yönergesine belirtilen ismi eklenir. (Günlük dosyalarınızın kişiselleştirilmesi ile ilgili daha fazla bilgi için mod_log_config belgesine bakınız.)

Günlük dosyanızdaki kayıtları bileşenlere göre gruplamak isterseniz split-logfile programını kullanabilirsiniz. Bu programı Apache dağıtımının support dizininde bulabilirsiniz.

Programı aşağıdaki gibi çalıştırın:

split-logfile < /logs/multiple_vhost_log

Bu programı sanal konaklar için tuttuğunuz günlük dosyasının ismini argüman olarak belirterek çalıştırdığınızda o dosyadaki kayıtlardan her sanal konak için ayrı bir günlük dosyası (konakadı.log) üretilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache mod_rewrite - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache mod_rewrite

mod_rewrite modülü gelen URL isteklerinde değişiklik yapabilmek için düzenli ifade kurallarına dayalı, devingen bir yol sunar. Böylece, keyfi URL'leri dahili URL yapınızla kolayca eşleyebilirsiniz.

Gerçekten esnek ve güçlü bir URL kurgulama mekanizması oluşturmak için sınısız sayıda kural ve her kural için de sınırsız sayıda koşul destekler. URL değişiklikleri çeşitli sınamalara dayanır; sunucu değişkenleri, HTTP başlıkları, ortam değişkenleri, zaman damgaları hatta çeşitli biçimlerde harici veritabanı sorguları bile bu amaçla kullanılabilir.

Yeniden yazma kuralları URL’lerin tamamında (path-info kısmı ve sorgu dizgesi dahil) hem sunucu bağlamında (httpd.conf) hem sanal konaklar bağlamında (<VirtualHost> bölümleri), hem de dizin bağlamında (.htaccess dosyaları ve <Directory> bölümleri) çalışır ve URL üzerinde sorgu dizgesi bölümleri bile oluşturabilir. Kurallara atadığınız seçeneklere bağlı olarak, yeniden yazılan URL sonuçta dahili işlemlerde, harici yönlendirmelerde ve vekalet işlemlerinde kullanılabilir.

mod_rewrite modülü çok güçlü olduğundan, gerçekten çok karmaşık olabilir. Bu belge, başvuru belgelerinin tamamlayıcısı olup karmaşıklığı biraz azaltmaya çalışır ve mod_rewrite ile elde edilebilen ortak senaryoların oldukça açıklamalı örneklerini sağlar. Fakat ayrıca, mod_rewrite modülünü kullanmamanız, yerine standart Apache özelliklerini kullanmanız gereken durumları da göstermeye, böylece gereksiz karmaşıklıktan kurtulmanızı sağlamaya çalıştık.

  • mod_rewrite başvuru belgesi
  • mod_rewrite ve düzenli ifadelere giriş
  • URL yönlendirme ve yeniden eşlemede mod_rewrite kullanımı
  • Erişimi denetlemekte mod_rewrite kullanımı
  • mod_rewrite ile devingen sanal konaklar
  • mod_rewrite ile devingen vekalet
  • RewriteMap kullanımı
  • İleri teknikler
  • mod_rewrite ne zaman kullanılmaMAlı
  • RewriteRule seçenekleri
  • Teknik ayrıntılar

Ayrıca bakınız:

  • mod_rewrite başvuru belgesi
  • URL’lerin Dosya Sistemine Eşlenmesi
  • mod_rewrite wiki
  • Terimler

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_rewrite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_rewrite

Description: | Provides a rule-based rewriting engine to rewrite requested URLs on the fly
Status: | Extension
Module Identifier: | rewrite_module
Source File: | mod_rewrite.c

Summary

The mod_rewrite module uses a rule-based rewriting engine, based on a PCRE regular-expression parser, to rewrite requested URLs on the fly. By default, mod_rewrite maps a URL to a filesystem path. However, it can also be used to redirect one URL to another URL, or to invoke an internal proxy fetch.

mod_rewrite provides a flexible and powerful way to manipulate URLs using an unlimited number of rules. Each rule can have an unlimited number of attached rule conditions, to allow you to rewrite URL based on server variables, environment variables, HTTP headers, or time stamps.

mod_rewrite operates on the full URL path, including the path-info section. A rewrite rule can be invoked in httpd.conf or in .htaccess. The path generated by a rewrite rule can include a query string, or can lead to internal sub-processing, external request redirection, or internal proxy throughput.

Further details, discussion, and examples, are provided in the detailed mod_rewrite documentation.

Logging

mod_rewrite offers detailed logging of its actions at the trace1 to trace8 log levels. The log level can be set specifically for mod_rewrite using the LogLevel directive: Up to level debug, no actions are logged, while trace8 means that practically all actions are logged.

Using a high trace log level for mod_rewrite will slow down your Apache HTTP Server dramatically! Use a log level higher than trace2 only for debugging!

Example

LogLevel alert rewrite:trace3

RewriteLog

Those familiar with earlier versions of mod_rewrite will no doubt be looking for the RewriteLog and RewriteLogLevel directives. This functionality has been completely replaced by the new per-module logging configuration mentioned above.

To get just the mod_rewrite-specific log messages, pipe the log file through grep:

tail -f error_log|fgrep '[rewrite:'

RewriteBase Directive

Description: | Sets the base URL for per-directory rewrites
Syntax: | RewriteBase URL-path
Default: | None
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteBase directive specifies the URL prefix to be used for per-directory (htaccess) RewriteRule directives that substitute a relative path.

This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless either of the following conditions are true:

  • The original request, and the substitution, are underneath the DocumentRoot (as opposed to reachable by other means, such as Alias).
  • The filesystem path to the directory containing the RewriteRule, suffixed by the relative substitution is also valid as a URL path on the server (this is rare).
  • In Apache HTTP Server 2.4.11 and later, this directive may be omitted when the request is mapped via Alias or mod_userdir.

In the example below, RewriteBase is necessary to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html since the resource was not relative to the document root. This misconfiguration would normally cause the server to look for an "opt" directory under the document root.

DocumentRoot "/var/www/example.com"
AliasMatch "^/myapp" "/opt/myapp-1.2.3"
<Directory "/opt/myapp-1.2.3">
    RewriteEngine On
    RewriteBase "/myapp/"
    RewriteRule "^index\.html$"  "welcome.html"
</Directory>

RewriteCond Directive

Description: | Defines a condition under which rewriting will take place
Syntax: | RewriteCond TestString CondPattern
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteCond directive defines a rule condition. One or more RewriteCond can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met.

TestString is a string which can contain the following expanded constructs in addition to plain text:

  • RewriteRule backreferences: These are backreferences of the form $N (0 <= N <= 9). $1 to $9 provide access to the grouped parts (in parentheses) of the pattern, from the RewriteRule which is subject to the current set of RewriteCond conditions. $0 provides access to the whole string matched by that pattern.
  • RewriteCond backreferences: These are backreferences of the form %N (0 <= N <= 9). %1 to %9 provide access to the grouped parts (again, in parentheses) of the pattern, from the last matched RewriteCond in the current set of conditions. %0 provides access to the whole string matched by that pattern.
  • RewriteMap expansions: These are expansions of the form ${mapname:key|default}. See the documentation for RewriteMap for more details.
  • Server-Variables: These are variables of the form %{ NAME_OF_VARIABLE } where NAME_OF_VARIABLE can be a string taken from the following list:
    HTTP headers: connection & request:
    HTTP_ACCEPT
    HTTP_COOKIE
    HTTP_FORWARDED
    HTTP_HOST
    HTTP_PROXY_CONNECTION
    HTTP_REFERER
    HTTP_USER_AGENT
             AUTH_TYPE
    CONN_REMOTE_ADDR
    CONTEXT_PREFIX
    CONTEXT_DOCUMENT_ROOT
    IPV6
    PATH_INFO
    QUERY_STRING
    REMOTE_ADDR
    REMOTE_HOST
    REMOTE_IDENT
    REMOTE_PORT
    REMOTE_USER
    REQUEST_METHOD
    SCRIPT_FILENAME
    server internals: date and time: specials:
    DOCUMENT_ROOT
    SCRIPT_GROUP
    SCRIPT_USER
    SERVER_ADDR
    SERVER_ADMIN
    SERVER_NAME
    SERVER_PORT
    SERVER_PROTOCOL
    SERVER_SOFTWARE
             TIME_YEAR
    TIME_MON
    TIME_DAY
    TIME_HOUR
    TIME_MIN
    TIME_SEC
    TIME_WDAY
    TIME
             API_VERSION
    CONN_REMOTE_ADDR
    HTTPS
    IS_SUBREQ
    REMOTE_ADDR
    REQUEST_FILENAME
    REQUEST_SCHEME
    REQUEST_URI
    THE_REQUEST

    These variables all correspond to the similarly named HTTP MIME-headers, C variables of the Apache HTTP Server or struct tm fields of the Unix system. Most are documented here or elsewhere in the Manual or in the CGI specification.

    SERVER_NAME and SERVER_PORT depend on the values of UseCanonicalName and UseCanonicalPhysicalPort respectively.

    Those that are special to mod_rewrite include those below.

    API_VERSION
    This is the version of the Apache httpd 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 httpd in use (in the release version of Apache httpd 1.3.14, for instance, it is 19990320:10), but is mainly of interest to module authors.
    CONN_REMOTE_ADDR
    Since 2.4.8: The peer IP address of the connection (see the mod_remoteip module).
    HTTPS
    Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise. (This variable can be safely used regardless of whether or not mod_ssl is loaded).
    IS_SUBREQ
    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.
    REMOTE_ADDR
    The IP address of the remote host (see the mod_remoteip module).
    REQUEST_FILENAME
    The full local filesystem path to the file or script matching the request, if this has already been determined by the server at the time REQUEST_FILENAME is referenced. Otherwise, such as when used in virtual host context, the same value as REQUEST_URI. Depending on the value of AcceptPathInfo, the server may have only used some leading components of the REQUEST_URI to map the request to a file.
    REQUEST_SCHEME
    Will contain the scheme of the request (usually "http" or "https"). This value can be influenced with ServerName.
    REQUEST_URI
    The path component of the requested URI, such as "/index.html". This notably excludes the query string which is available as its own variable named QUERY_STRING.
    THE_REQUEST
    The full HTTP request line sent by the browser to the server (e.g., "GET /index.html HTTP/1.1"). This does not include any additional headers sent by the browser. This value has not been unescaped (decoded), unlike most other variables below.

If the TestString has the special value expr, the CondPattern will be treated as an ap_expr. HTTP headers referenced in the expression will be added to the Vary header if the novary flag is not given.

Other things you should be aware of:

  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same value - the value of the filename field of the internal request_rec structure of the Apache HTTP Server. The first name is the commonly known CGI variable name while the second is the appropriate counterpart of REQUEST_URI (which contains the value of the uri field of request_rec).

    If a substitution occurred and the rewriting continues, the value of both variables will be updated accordingly.

    If used in per-server context (i.e., before the request is mapped to the filesystem) SCRIPT_FILENAME and REQUEST_FILENAME cannot contain the full local filesystem path since the path is unknown at this stage of processing. Both variables will initially contain the value of REQUEST_URI in that case. In order to obtain the full local filesystem path of the request in per-server context, use an URL-based look-ahead %{LA-U:REQUEST_FILENAME} to determine the final value of REQUEST_FILENAME.

  2. %{ENV:variable}, where variable can be any environment variable, is also available. This is looked-up via internal Apache httpd structures and (if not found there) via getenv() from the Apache httpd server process.
  3. %{SSL:variable}, where variable is the name of an SSL environment variable, can be used whether or not mod_ssl is loaded, but will always expand to the empty string if it is not. Example: %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to 128. These variables are available even without setting the StdEnvVars option of the SSLOptions directive.
  4. %{HTTP:header}, where header can be any HTTP MIME-header name, can always be used to obtain the value of a header sent in the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''.

    If a HTTP header is used in a condition this header is added to the Vary header of the response in case the condition evaluates to true for the request. It is not added if the condition evaluates to false for the request. Adding the HTTP header to the Vary header of the response is needed for proper caching.

    It has to be kept in mind that conditions follow a short circuit logic in the case of the 'ornext|OR' flag so that certain conditions might not be evaluated at all.

  5. %{LA-U:variable} can be used for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. This can be used to access variable for rewriting which is not available at the current stage, but will be set in a later phase.

    For instance, to rewrite according to the REMOTE_USER variable from within the per-server context (httpd.conf file) you must use %{LA-U:REMOTE_USER} - this variable is set by the authorization phases, which come after the URL translation phase (during which mod_rewrite operates).

    On the other hand, because mod_rewrite implements its per-directory context (.htaccess file) via the Fixup phase of the API and because the authorization phases come before this phase, you just can use %{REMOTE_USER} in that context.

  6. %{LA-F:variable} can be used to perform an internal (filename-based) sub-request, to determine the final value of variable. Most of the time, this is the same as LA-U above.

CondPattern is the condition pattern, a regular expression which is applied to the current instance of the TestString. TestString is first evaluated, before being matched against CondPattern.

CondPattern is usually a perl compatible regular expression, but there is additional syntax available to perform other useful tests against the Teststring:

  1. You can prefix the pattern string with a '!' character (exclamation mark) to negate the result of the condition, no matter what kind of CondPattern is used.
  2. You can perform lexicographical string comparisons:
    <CondPattern
    Lexicographically precedes
    Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically precedes CondPattern.
    >CondPattern
    Lexicographically follows
    Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern.
    =CondPattern
    Lexicographically equal
    Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString is lexicographically equal to CondPattern (the two strings are exactly equal, character for character). If CondPattern is "" (two quotation marks) this compares TestString to the empty string.
    <=CondPattern
    Lexicographically less than or equal to
    Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically precedes CondPattern, or is equal to CondPattern (the two strings are equal, character for character).
    >=CondPattern
    Lexicographically greater than or equal to
    Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern, or is equal to CondPattern (the two strings are equal, character for character).
  3. You can perform integer comparisons:
    -eq
    Is numerically equal to
    The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the two are numerically equal.
    -ge
    Is numerically greater than or equal to
    The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically greater than or equal to the CondPattern.
    -gt
    Is numerically greater than
    The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically greater than the CondPattern.
    -le
    Is numerically less than or equal to
    The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically less than or equal to the CondPattern. Avoid confusion with the -l by using the -L or -h variant.
    -lt
    Is numerically less than
    The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically less than the CondPattern. Avoid confusion with the -l by using the -L or -h variant.
  4. You can perform various file attribute tests:
    -d
    Is directory.
    Treats the TestString as a pathname and tests whether or not it exists, and is a directory.
    -f
    Is regular file.
    Treats the TestString as a pathname and tests whether or not it exists, and is a regular file.
    -F
    Is existing file, via subrequest.
    Checks whether or not TestString is a valid file, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance!
    -H
    Is symbolic link, bash convention.
    See -l.
    -l
    Is symbolic link.
    Treats the TestString as a pathname and tests whether or not it exists, and is a symbolic link. May also use the bash convention of -L or -h if there's a possibility of confusion such as when using the -lt or -le tests.
    -L
    Is symbolic link, bash convention.
    See -l.
    -s
    Is regular file, with size.
    Treats the TestString as a pathname and tests whether or not it exists, and is a regular file with size greater than zero.
    -U

    Is existing URL, via subrequest.
    Checks whether or not TestString is a valid URL, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance!

    This flag only returns information about things like access control, authentication, and authorization. This flag does not return information about the status code the configured handler (static file, CGI, proxy, etc.) would have returned.

    -x
    Has executable permissions.
    Treats the TestString as a pathname and tests whether or not it exists, and has executable permissions. These permissions are determined according to the underlying OS.
    For example:
    RewriteCond /var/www/%{REQUEST_URI} !-f
RewriteRule ^(.+) /other/archive/$1 [R]

  5. If the TestString has the special value expr, the CondPattern will be treated as an ap_expr.

    In the below example, -strmatch is used to compare the REFERER against the site hostname, to block unwanted hotlinking.

    RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"

RewriteRule "^/images" "-" [F]
  6. You can also set special flags for CondPattern by appending [flags] as the third argument to the RewriteCond directive, where flags is a comma-separated list of any of the following flags:
    • 'nocase|NC' (no case)
      This makes the test case-insensitive - differences between 'A-Z' and 'a-z' are ignored, both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no effect on filesystem and subrequest checks.
    • 'ornext|OR' (or next condition)
      Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example:
      RewriteCond "%{REMOTE_HOST}"  "^host1"  [OR]
RewriteCond "%{REMOTE_HOST}"  "^host2"  [OR]
RewriteCond "%{REMOTE_HOST}"  "^host3"
RewriteRule ...some special stuff for any of these hosts...
      Without this flag you would have to write the condition/rule pair three times.
    • 'novary|NV' (no vary)
      If a HTTP header is used in the condition, this flag prevents this header from being added to the Vary header of the response.
      Using this flag might break proper caching of the response if the representation of this response varies on the value of this header. So this flag should be only used if the meaning of the Vary header is well understood.

Example:

To rewrite the Homepage of a site according to the ``User-Agent:'' header of the request, you can use the following:

RewriteCond  "%{HTTP_USER_AGENT}"  "(iPhone|Blackberry|Android)"
RewriteRule  "^/$"                 "/homepage.mobile.html"  [L]

RewriteRule  "^/$"                 "/homepage.std.html"  [L]

Explanation: If you use a browser which identifies itself as a mobile browser (note that the example is incomplete, as there are many other mobile platforms), the mobile version of the homepage is served. Otherwise, the standard page is served.

RewriteEngine Directive

Description: | Enables or disables runtime rewriting engine
Syntax: | RewriteEngine on|off
Default: | RewriteEngine off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteEngine directive enables or disables the runtime rewriting engine. If it is set to off this module does no runtime processing at all. It does not even update the SCRIPT_URx environment variables.

Use this directive to disable rules in a particular context, rather than commenting out all the RewriteRule directives.

Note that rewrite configurations are not inherited by virtual hosts. This means that you need to have a RewriteEngine on directive for each virtual host in which you wish to use rewrite rules.

RewriteMap directives of the type prg are not started during server initialization if they're defined in a context that does not have RewriteEngine set to on

RewriteMap Directive

Description: | Defines a mapping function for key-lookup
Syntax: | RewriteMap MapName MapType:MapSource MapTypeOptions
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite

The RewriteMap directive defines a Rewriting Map 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.

The MapName 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:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified. Empty values behave as if the key was absent, therefore it is not possible to distinguish between empty-valued keys and absent keys.

For example, you might define a RewriteMap as:

RewriteMap examplemap "txt:/path/to/file/map.txt"

You would then be able to use this map in a RewriteRule as follows:

RewriteRule "^/ex/(.*)" "${examplemap:$1}"

The meaning of the MapTypeOptions argument depends on particular MapType. See the Using RewriteMap for more information.

The following combinations for MapType and MapSource can be used:

txt
A plain text file containing space-separated key-value pairs, one per line. (Details ...)
rnd
Randomly selects an entry from a plain text file (Details ...)
dbm
Looks up an entry in a dbm file containing name, value pairs. Hash is constructed from a plain text file format using the httxt2dbm utility. (Details ...)
int
One of the four available internal functions provided by RewriteMap: toupper, tolower, escape or unescape. (Details ...)
prg
Calls an external program or script to process the rewriting. (Details ...)
dbd or fastdbd
A SQL SELECT statement to be performed to look up the rewrite target. (Details ...)

Further details, and numerous examples, may be found in the RewriteMap HowTo

RewriteOptions Directive

Description: | Sets some special options for the rewrite engine
Syntax: | RewriteOptions Options
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteOptions directive sets some special options for the current per-server or per-directory configuration. The Option string can currently only be one of the following:

Inherit

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 .htaccess configuration or <Directory> sections are inherited. The inherited rules are virtually copied to the section where this directive is being used. If used in combination with local rules, the inherited rules are copied behind the local rules. The position of this directive - below or above of local rules - has no influence on this behavior. If local rules forced the rewriting to stop, the inherited rules won't be processed.

Rules inherited from the parent scope are applied after rules specified in the child scope.
InheritBefore

Like Inherit above, but the rules from the parent scope are applied before rules specified in the child scope.
Available in Apache HTTP Server 2.3.10 and later.

InheritDown

If this option is enabled, all child configurations will inherit the configuration of the current configuration. It is equivalent to specifying RewriteOptions Inherit in all child configurations. See the Inherit option for more details on how the parent-child relationships are handled.
Available in Apache HTTP Server 2.4.8 and later.

InheritDownBefore

Like InheritDown above, but the rules from the current scope are applied before rules specified in any child's scope.
Available in Apache HTTP Server 2.4.8 and later.

IgnoreInherit

This option forces the current and child configurations to ignore all rules that would be inherited from a parent specifying InheritDown or InheritDownBefore.
Available in Apache HTTP Server 2.4.8 and later.

AllowNoSlash

By default, mod_rewrite will ignore URLs that map to a directory on disk but lack a trailing slash, in the expectation that the mod_dir module will issue the client with a redirect to the canonical URL with a trailing slash.

When the DirectorySlash directive is set to off, the AllowNoSlash option can be enabled to ensure that rewrite rules are no longer ignored. This option makes it possible to apply rewrite rules within .htaccess files that match the directory without a trailing slash, if so desired.
Available in Apache HTTP Server 2.4.0 and later.

AllowAnyURI

When RewriteRule is used in VirtualHost or server context with version 2.2.22 or later of httpd, mod_rewrite will only process the rewrite rules if the request URI is a URL-path. This avoids some security issues where particular rules could allow "surprising" pattern expansions (see CVE-2011-3368 and CVE-2011-4317). To lift the restriction on matching a URL-path, the AllowAnyURI option can be enabled, and mod_rewrite will apply the rule set to any request URI string, regardless of whether that string matches the URL-path grammar required by the HTTP specification.
Available in Apache HTTP Server 2.4.3 and later.

Security Warning

Enabling this option will make the server vulnerable to security issues if used with rewrite rules which are not carefully authored. It is strongly recommended that this option is not used. In particular, beware of input strings containing the '@' character which could change the interpretation of the transformed URI, as per the above CVE names.

MergeBase

With this option, the value of RewriteBase is copied from where it's explicitly defined into any sub-directory or sub-location that doesn't define its own RewriteBase. This was the default behavior in 2.4.0 through 2.4.3, and the flag to restore it is available Apache HTTP Server 2.4.4 and later.

IgnoreContextInfo

When a relative substitution is made in directory (htaccess) context and RewriteBase has not been set, this module uses some extended URL and filesystem context information to change the relative substitution back into a URL. Modules such as mod_userdir and mod_alias supply this extended context info.

RewriteRule Directive

Description: | Defines rules for the rewriting engine
Syntax: | RewriteRule Pattern Substitution [flags]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time.

Pattern is a perl compatible regular expression. On the first RewriteRule, it is matched against the (%-decoded) URL-path of the request, or, in per-directory context (see below), the URL path relative to that per-directory context. Subsequent patterns are matched against the output of the last matching RewriteRule.

What is matched?

In VirtualHost context, The Pattern will initially be matched against the part of the URL after the hostname and port, and before the query string (e.g. "/app1/index.html").

In Directory and htaccess context, the Pattern will initially be matched against the filesystem path, after removing the prefix that led the server to the current RewriteRule (e.g. "app1/index.html" or "index.html" depending on where the directives are defined).

If you wish to match against the hostname, port, or query string, use a RewriteCond with the %{HTTP_HOST}, %{SERVER_PORT}, or %{QUERY_STRING} variables respectively.

In any case, remember that regular expressions are substring matches. That is, you don't need the regex to describe the entire string, just the part that you wish to match. Thus, using a regex of . is often sufficient rather than .*, and the regex abc is not the same as ^abc$.

Per-directory Rewrites

  • The rewrite engine may be used in .htaccess files and in <Directory> sections, with some additional complexity.
  • To enable the rewrite engine in this context, you need to set "RewriteEngine On" and "Options FollowSymLinks" must be enabled. If your administrator has disabled override of FollowSymLinks for a user's directory, then you cannot use the rewrite engine. This restriction is required for security reasons.
  • When using the rewrite engine in .htaccess files the per-directory prefix (which always is the same for a specific directory) is automatically removed for the RewriteRule pattern matching and automatically added after any relative (not starting with a slash or protocol name) substitution encounters the end of a rule set. See the RewriteBase directive for more information regarding what prefix will be added back to relative substitutions.
  • If you wish to match against the full URL-path in a per-directory (htaccess) RewriteRule, use the %{REQUEST_URI} variable in a RewriteCond.
  • The removed prefix always ends with a slash, meaning the matching occurs against a string which never has a leading slash. Therefore, a Pattern with ^/ never matches in per-directory context.
  • Although rewrite rules are syntactically permitted in <Location> and <Files> sections (including their regular expression counterparts), this should never be necessary and is unsupported. A likely feature to break in these contexts is relative substitutions.

For some hints on regular expressions, see the mod_rewrite Introduction.

In mod_rewrite, the NOT character ('!') is also available as a possible pattern prefix. This enables you to negate a pattern; to say, for instance: ``if the current URL does NOT match this pattern''. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

Note

When using the NOT character to negate a pattern, you cannot include grouped wildcard parts in that pattern. This is because, when the pattern does NOT match (ie, the negation matches), there are no contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string!

The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a:

file-system path
Designates the location on the file-system of the resource to be delivered to the client. Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution exists in the file-system
URL-path
A DocumentRoot-relative path to the resource to be served. Note that mod_rewrite tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html, then this will be treated as a URL-path unless a directory named www exists at the root or your file-system (or, in the case of using rewrites in a .htaccess file, relative to your document root), in which case it will be treated as a file-system path. If you wish other URL-mapping directives (such as Alias) to be applied to the resulting URL-path, use the [PT] flag as described below.
Absolute URL
If an absolute URL is specified, mod_rewrite checks to see whether the hostname matches the current host. If it does, the scheme and hostname are stripped out and the resulting path is treated as a URL-path. Otherwise, an external redirect is performed for the given URL. To force an external redirect back to the current host, see the [R] flag below.
- (dash)
A dash indicates that no substitution should be performed (the existing path is passed through untouched). This is used when a flag (see below) needs to be applied without changing the path.

In addition to plain text, the Substitution string can include

  1. back-references ($N) to the RewriteRule pattern
  2. back-references (%N) to the last matched RewriteCond pattern
  3. server-variables as in rule condition test-strings (%{VARNAME})
  4. mapping-function calls (${mapname:key|default})

Back-references are identifiers of the form $N (N=0..9), which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a RewriteCond directive. The mapping-functions come from the RewriteMap directive and are explained there. These three types of variables are expanded in the order above.

Rewrite rules are applied to the results of previous rewrite rules, in the order in which they are defined in the config file. The URL-path or file-system path (see "What is matched?", above) is completely replaced by the Substitution and the rewriting process continues until all rules have been applied, or it is explicitly terminated by an L flag, or other flag which implies immediate termination, such as END or F.

Modifying the Query String

By default, the query string is passed through unchanged. You can, however, create URLs in the substitution string containing a query string part. Simply use a question mark inside the substitution string to indicate that the following text should be re-injected into the query string. When you want to erase an existing query string, end the substitution string with just a question mark. To combine new and old query strings, use the [QSA] flag.

Additionally you can set special actions to be performed by appending [flags] as the third argument to the RewriteRule directive. Flags is a comma-separated list, surround by square brackets, of any of the flags in the following table. More details, and examples, for each flag, are available in the Rewrite Flags document.

Flag and syntax | Function
B | Escape non-alphanumeric characters in backreferences before applying the transformation. details ...
backrefnoplus|BNP | If backreferences are being escaped, spaces should be escaped to %20 instead of +. Useful when the backreference will be used in the path component rather than the query string.details ...
chain|C | Rule is chained to the following rule. If the rule fails, the rule(s) chained to it will be skipped. details ...
cookie|CO=NAME:VAL | Sets a cookie in the client browser. Full syntax is: CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ...
discardpath|DPI | Causes the PATH_INFO portion of the rewritten URI to be discarded. details ...
END | Stop the rewriting process immediately and don't apply any more rules. Also prevents further execution of rewrite rules in per-directory and .htaccess context. (Available in 2.3.9 and later) details ...
env|E=[!]VAR[:VAL] | Causes an environment variable VAR to be set (to the value VAL if provided). The form !VAR causes the environment variable VAR to be unset. details ...
forbidden|F | Returns a 403 FORBIDDEN response to the client browser. details ...
gone|G | Returns a 410 GONE response to the client browser. details ...
Handler|H=Content-handler | Causes the resulting URI to be sent to the specified Content-handler for processing. details ...
last|L | Stop the rewriting process immediately and don't apply any more rules. Especially note caveats for per-directory and .htaccess context (see also the END flag). details ...
next|N | Re-run the rewriting process, starting again with the first rule, using the result of the ruleset so far as a starting point. details ...
nocase|NC | Makes the pattern comparison case-insensitive. details ...
noescape|NE | Prevent mod_rewrite from applying hexcode escaping of special characters in the result of the rewrite. details ...
nosubreq|NS | Causes a rule to be skipped if the current request is an internal sub-request. details ...
proxy|P | Force the substitution URL to be internally sent as a proxy request. details ...
passthrough|PT | Forces the resulting URI to be passed back to the URL mapping engine for processing of other URI-to-filename translators, such as Alias or Redirect. details ...
qsappend|QSA | Appends any query string from the original request URL to any query string created in the rewrite target.details ...
qsdiscard|QSD | Discard any query string attached to the incoming URI. details ...
qslast|QSL | Interpret the last (right-most) question mark as the query string delimeter, instead of the first (left-most) as normally used. Available in 2.4.19 and later. details ...
redirect|R[=code] | Forces an external redirect, optionally with the specified HTTP status code. details ...
skip|S=num | Tells the rewriting engine to skip the next num rules if the current rule matches. details ...
type|T=MIME-type | Force the MIME-type of the target file to be the specified type. details ...

Home directory expansion

When the substitution string begins with a string resembling "/~user" (via explicit text or backreferences), mod_rewrite performs home directory expansion independent of the presence or configuration of mod_userdir.

This expansion does not occur when the PT flag is used on the RewriteRule directive.

Here are all possible substitution combinations and their meanings:

Inside per-server configuration (httpd.conf)
for request ``GET /somepath/pathinfo'':

Given Rule | Resulting Substitution
^/somepath(.*) otherpath$1 | invalid, not supported
^/somepath(.*) otherpath$1 [R] | invalid, not supported
^/somepath(.*) otherpath$1 [P] | invalid, not supported
^/somepath(.*) /otherpath$1 | /otherpath/pathinfo
^/somepath(.*) /otherpath$1 [R] | http://thishost/otherpath/pathinfo via external redirection
^/somepath(.*) /otherpath$1 [P] | doesn't make sense, not supported
^/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] | doesn't make sense, not supported
^/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

Inside per-directory configuration for /somepath
(/physical/path/to/somepath/.htaccess, with RewriteBase "/somepath")
for request ``GET /somepath/localpath/pathinfo'':

Given Rule | Resulting Substitution
^localpath(.*) otherpath$1 | /somepath/otherpath/pathinfo
^localpath(.*) otherpath$1 [R] | http://thishost/somepath/otherpath/pathinfo via external redirection
^localpath(.*) otherpath$1 [P] | doesn't make sense, not supported
^localpath(.*) /otherpath$1 | /otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] | http://thishost/otherpath/pathinfo via external redirection
^localpath(.*) /otherpath$1 [P] | doesn't make sense, not supported
^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] | doesn't make sense, not supported
^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


Apache mod_rewrite Introduction - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Apache mod_rewrite Introduction

This document supplements the mod_rewrite reference documentation. It describes the basic concepts necessary for use of mod_rewrite. Other documents go into greater detail, but this doc should help the beginner get their feet wet.

See also

  • Module documentation
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Introduction

The Apache module mod_rewrite is a very powerful and sophisticated module which provides a way to do URL manipulations. With it, you can do nearly all types of URL rewriting that you may need. It is, however, somewhat complex, and may be intimidating to the beginner. There is also a tendency to treat rewrite rules as magic incantation, using them without actually understanding what they do.

This document attempts to give sufficient background so that what follows is understood, rather than just copied blindly.

Remember that many common URL-manipulation tasks don't require the full power and complexity of mod_rewrite. For simple tasks, see mod_alias and the documentation on mapping URLs to the filesystem.

Finally, before proceeding, be sure to configure mod_rewrite's log level to one of the trace levels using the LogLevel directive. Although this can give an overwhelming amount of information, it is indispensable in debugging problems with mod_rewrite configuration, since it will tell you exactly how each rule is processed.

Regular Expressions

mod_rewrite uses the Perl Compatible Regular Expression vocabulary. In this document, we do not attempt to provide a detailed reference to regular expressions. For that, we recommend the PCRE man pages, the Perl regular expression man page, and Mastering Regular Expressions, by Jeffrey Friedl.

In this document, we attempt to provide enough of a regex vocabulary to get you started, without being overwhelming, in the hope that RewriteRules will be scientific formulae, rather than magical incantations.

Regex vocabulary

The following are the minimal building blocks you will need, in order to write regular expressions and RewriteRules. They certainly do not represent a complete regular expression vocabulary, but they are a good place to start, and should help you read basic regular expressions, as well as write your own.

Character | Meaning | Example
. | Matches any single character | c.t will match cat, cot, cut, etc.
+ | Repeats the previous match one or more times | a+ matches a, aa, aaa, etc
* | Repeats the previous match zero or more times. | a* matches all the same things a+ matches, but will also match an empty string.
? | Makes the match optional. | colou?r will match color and colour.
^ | Called an anchor, matches the beginning of the string | ^a matches a string that begins with a
$ | The other anchor, this matches the end of the string. | a$ matches a string that ends with a.
( ) | Groups several characters into a single unit, and captures a match for use in a backreference. | (ab)+ matches ababab - that is, the + applies to the group. For more on backreferences see below.
[ ] | A character class - matches one of the characters | c[uoa]t matches cut, cot or cat.
[^ ] | Negative character class - matches any character not specified | c[^/]t matches cat or c=t but not c/t

In mod_rewrite the ! character can be used before a regular expression to negate it. This is, a string will be considered to have matched only if it does not match the rest of the expression.

Regex Back-Reference Availability

One important thing here has to be remembered: Whenever you use parentheses in Pattern or in one of the CondPattern, back-references are internally created which can be used with the strings $N and %N (see below). These are available for creating the Substitution parameter of a RewriteRule or the TestString parameter of a RewriteCond.

Captures in the RewriteRule patterns are (counterintuitively) available to all preceding RewriteCond directives, because the RewriteRule expression is evaluated before the individual conditions.

Figure 1 shows to which locations the back-references are transferred for expansion as well as illustrating the flow of the RewriteRule, RewriteCond matching. In the next chapters, we will be exploring how to use these back-references, so do not fret if it seems a bit alien to you at first.

Flow of RewriteRule and RewriteCond matching
Figure 1: The back-reference flow through a rule.
In this example, a request for /test/1234 would be transformed into /admin.foo?page=test&id=1234&host=admin.example.com.

RewriteRule Basics

A RewriteRule consists of three arguments separated by spaces. The arguments are

  1. Pattern: which incoming URLs should be affected by the rule;
  2. Substitution: where should the matching requests be sent;
  3. [flags]: options affecting the rewritten request.

The Pattern is a regular expression. It is initially (for the first rewrite rule or until a substitution occurs) matched against the URL-path of the incoming request (the part after the hostname but before any question mark indicating the beginning of a query string) or, in per-directory context, against the request's path relative to the directory for which the rule is defined. Once a substitution has occurred, the rules that follow are matched against the substituted value.

Syntax of the RewriteRule directive
Figure 2: Syntax of the RewriteRule directive.

The Substitution can itself be one of three things:

A full filesystem path to a resource
RewriteRule "^/games" "/usr/local/games/web"

This maps a request to an arbitrary location on your filesystem, much like the Alias directive.

A web-path to a resource
RewriteRule "^/foo$" "/bar"

If DocumentRoot is set to /usr/local/apache2/htdocs, then this directive would map requests for http://example.com/foo to the path /usr/local/apache2/htdocs/bar.

An absolute URL
RewriteRule "^/product/view$" "http://site2.example.com/seeproduct.html" [R]

This tells the client to make a new request for the specified URL.

The Substitution can also contain back-references to parts of the incoming URL-path matched by the Pattern. Consider the following:

RewriteRule "^/product/(.*)/view$" "/var/web/productdb/$1"

The variable $1 will be replaced with whatever text was matched by the expression inside the parenthesis in the Pattern. For example, a request for http://example.com/product/r14df/view will be mapped to the path /var/web/productdb/r14df.

If there is more than one expression in parenthesis, they are available in order in the variables $1, $2, $3, and so on.

Rewrite Flags

The behavior of a RewriteRule can be modified by the application of one or more flags to the end of the rule. For example, the matching behavior of a rule can be made case-insensitive by the application of the [NC] flag:

RewriteRule "^puppy.html" "smalldog.html" [NC]

For more details on the available flags, their meanings, and examples, see the Rewrite Flags document.

Rewrite Conditions

One or more RewriteCond directives can be used to restrict the types of requests that will be subject to the following RewriteRule. The first argument is a variable describing a characteristic of the request, the second argument is a regular expression that must match the variable, and a third optional argument is a list of flags that modify how the match is evaluated.

Syntax of the RewriteCond directive
Figure 3: Syntax of the RewriteCond directive

For example, to send all requests from a particular IP range to a different server, you could use:

RewriteCond "%{REMOTE_ADDR}" "^10\.2\."
RewriteRule "(.*)" "http://intranet.example.com$1"

When more than one RewriteCond is specified, they must all match for the RewriteRule to be applied. For example, to deny requests that contain the word "hack" in their query string, unless they also contain a cookie containing the word "go", you could use:

RewriteCond "%{QUERY_STRING}" "hack"
RewriteCond "%{HTTP_COOKIE}" "!go"
RewriteRule "." "-" [F]

Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".

Matches in the regular expressions contained in the RewriteConds can be used as part of the Substitution in the RewriteRule using the variables %1, %2, etc. For example, this will direct the request to a different directory depending on the hostname used to access the site:

RewriteCond "%{HTTP_HOST}" "(.*)"
RewriteRule "^/(.*)" "/sites/%1/$1"

If the request was for http://example.com/foo/bar, then %1 would contain example.com and $1 would contain foo/bar.

Rewrite maps

The RewriteMap directive provides a way to call an external function, so to speak, to do your rewriting for you. This is discussed in greater detail in the RewriteMap supplementary documentation.

.htaccess files

Rewriting is typically configured in the main server configuration setting (outside any <Directory> section) or inside <VirtualHost> containers. This is the easiest way to do rewriting and is recommended. It is possible, however, to do rewriting inside <Directory> sections or .htaccess files at the expense of some additional complexity. This technique is called per-directory rewrites.

The main difference with per-server rewrites is that the path prefix of the directory containing the .htaccess file is stripped before matching in the RewriteRule. In addition, the RewriteBase should be used to assure the request is properly mapped.


Redirecting and Remapping with mod_rewrite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Redirecting and Remapping with mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to redirect and remap request. This includes many examples of common uses of mod_rewrite, including detailed descriptions of how each works.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

From Old to New (internal)

Description:

Assume we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. However, we want that users of the old URL even not recognize that the pages was renamed - that is, we don't want the address to change in their browser.

Solution:

We rewrite the old URL to the new one internally via the following rule:

RewriteEngine  on
RewriteRule    "^/foo\.html$"  "/bar.html" [PT]

Rewriting From Old to New (external)

Description:

Assume again that we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. But this time we want that the users of the old URL get hinted to the new one, i.e. their browsers Location field should change, too.

Solution:

We force a HTTP redirect to the new URL which leads to a change of the browsers and thus the users view:

RewriteEngine  on
RewriteRule    "^/foo\.html$"  "bar.html"  [R]
Discussion

In this example, as contrasted to the internal example above, we can simply use the Redirect directive. mod_rewrite was used in that earlier example in order to hide the redirect from the client:

Redirect "/foo.html" "/bar.html"

Resource Moved to Another Server

Description:

If a resource has moved to another server, you may wish to have URLs continue to work for a time on the old server while people update their bookmarks.

Solution:

You can use mod_rewrite to redirect these URLs to the new server, but you might also consider using the Redirect or RedirectMatch directive.

#With mod_rewrite
RewriteEngine on
RewriteRule   "^/docs/(.+)"  "http://new.example.com/docs/$1"  [R,L]
#With RedirectMatch
RedirectMatch "^/docs/(.*)" "http://new.example.com/docs/$1"
#With Redirect
Redirect "/docs/" "http://new.example.com/docs/"

From Static to Dynamic

Description:

How can we transform a static page foo.html into a dynamic variant foo.cgi in a seamless way, i.e. without notice by the browser/user.

Solution:

We just rewrite the URL to the CGI-script and force the handler to be cgi-script so that it is executed as a CGI program. This way a request to /~quux/foo.html internally leads to the invocation of /~quux/foo.cgi.

RewriteEngine  on
RewriteBase    "/~quux/"
RewriteRule    "^foo\.html$"  "foo.cgi"   [H=cgi-script]

Backward Compatibility for file extension change

Description:

How can we make URLs backward compatible (still existing virtually) after migrating document.YYYY to document.XXXX, e.g. after translating a bunch of .html files to .php?

Solution:

We rewrite the name to its basename and test for existence of the new extension. If it exists, we take that name, else we rewrite the URL to its original state.

#   backward compatibility ruleset for
#   rewriting document.html to document.php
#   when and only when document.php exists
<Directory "/var/www/htdocs">
    RewriteEngine on
    RewriteBase "/var/www/htdocs"

    RewriteCond "$1.php" -f
    RewriteCond "$1.html" !-f
    RewriteRule "^(.*).html$" "$1.php"
</Directory>
Discussion

This example uses an often-overlooked feature of mod_rewrite, by taking advantage of the order of execution of the ruleset. In particular, mod_rewrite evaluates the left-hand-side of the RewriteRule before it evaluates the RewriteCond directives. Consequently, $1 is already defined by the time the RewriteCond directives are evaluated. This allows us to test for the existence of the original (document.html) and target (document.php) files using the same base filename.

This ruleset is designed to use in a per-directory context (In a <Directory> block or in a .htaccess file), so that the -f checks are looking at the correct directory path. You may need to set a RewriteBase directive to specify the directory base that you're working in.

Canonical Hostnames

Description:
The goal of this rule is to force the use of a particular hostname, in preference to other hostnames which may be used to reach the same site. For example, if you wish to force the use of www.example.com instead of example.com, you might use a variant of the following recipe.
Solution:

The very best way to solve this doesn't involve mod_rewrite at all, but rather uses the Redirect directive placed in a virtual host for the non-canonical hostname(s).

<VirtualHost *:80>
  ServerName undesired.example.com
  ServerAlias example.com notthis.example.com

  Redirect "/" "http://www.example.com/"
</VirtualHost>

<VirtualHost *:80>
  ServerName www.example.com
</VirtualHost>

You can alternatively accomplish this using the <If> directive:

<If "%{HTTP_HOST} != 'www.example.com'">
    Redirect "/" "http://www.example.com/"
</If>

Or, for example, to redirect a portion of your site to HTTPS, you might do the following:

<If "%{SERVER_PROTOCOL} != 'HTTPS'">
    Redirect "/admin/" "https://www.example.com/admin/"
</If>

If, for whatever reason, you still want to use mod_rewrite - if, for example, you need this to work with a larger set of RewriteRules - you might use one of the recipes below.

For sites running on a port other than 80:

RewriteCond "%{HTTP_HOST}"   "!^www\.example\.com" [NC]
RewriteCond "%{HTTP_HOST}"   "!^$"
RewriteCond "%{SERVER_PORT}" "!^80$"
RewriteRule "^/?(.*)         "http://www.example.com:%{SERVER_PORT}/$1" [L,R,NE]

And for a site running on port 80

RewriteCond "%{HTTP_HOST}"   "!^www\.example\.com" [NC]
RewriteCond "%{HTTP_HOST}"   "!^$"
RewriteRule "^/?(.*)"        "http://www.example.com/$1" [L,R,NE]

If you wanted to do this generically for all domain names - that is, if you want to redirect example.com to www.example.com for all possible values of example.com, you could use the following recipe:

RewriteCond "%{HTTP_HOST}" "!^www\." [NC]
RewriteCond "%{HTTP_HOST}" "!^$"
RewriteRule "^/?(.*)"      "http://www.%{HTTP_HOST}/$1" [L,R,NE]

These rulesets will work either in your main server configuration file, or in a .htaccess file placed in the DocumentRoot of the server.

Search for pages in more than one directory

Description:

A particular resource might exist in one of several places, and we want to look in those places for the resource when it is requested. Perhaps we've recently rearranged our directory structure, dividing content into several locations.

Solution:

The following ruleset searches in two directories to find the resource, and, if not finding it in either place, will attempt to just serve it out of the location requested.

RewriteEngine on

#   first try to find it in dir1/...
#   ...and if found stop and be happy:
RewriteCond         "%{DOCUMENT_ROOT}/dir1/%{REQUEST_URI}"  -f
RewriteRule "^(.+)" "%{DOCUMENT_ROOT}/dir1/$1"  [L]

#   second try to find it in dir2/...
#   ...and if found stop and be happy:
RewriteCond         "%{DOCUMENT_ROOT}/dir2/%{REQUEST_URI}"  -f
RewriteRule "^(.+)" "%{DOCUMENT_ROOT}/dir2/$1"  [L]

#   else go on for other Alias or ScriptAlias directives,
#   etc.
RewriteRule   "^"  "-"  [PT]

Redirecting to Geographically Distributed Servers

Description:

We have numerous mirrors of our website, and want to redirect people to the one that is located in the country where they are located.

Solution:

Looking at the hostname of the requesting client, we determine which country they are coming from. If we can't do a lookup on their IP address, we fall back to a default server.

We'll use a RewriteMap directive to build a list of servers that we wish to use.

HostnameLookups on
RewriteEngine on
RewriteMap    multiplex         "txt:/path/to/map.mirrors"
RewriteCond   "%{REMOTE_HOST}"  "([a-z]+)$" [NC]
RewriteRule   "^/(.*)$"  "${multiplex:%1|http://www.example.com/}$1"  [R,L]

## map.mirrors -- Multiplexing Map

de http://www.example.de/
uk http://www.example.uk/
com http://www.example.com/
##EOF##

Discussion
This ruleset relies on HostNameLookups being set on, which can be a significant performance hit.

The RewriteCond directive captures the last portion of the hostname of the requesting client - the country code - and the following RewriteRule uses that value to look up the appropriate mirror host in the map file.

Browser Dependent Content

Description:

We wish to provide different content based on the browser, or user-agent, which is requesting the content.

Solution:

We have to decide, based on the HTTP header "User-Agent", which content to serve. The following config does the following: If the HTTP header "User-Agent" contains "Mozilla/3", the page foo.html is rewritten to foo.NS.html and the rewriting stops. If the browser is "Lynx" or "Mozilla" of version 1 or 2, the URL becomes foo.20.html. All other browsers receive page foo.32.html. This is done with the following ruleset:

RewriteCond "%{HTTP_USER_AGENT}"  "^Mozilla/3.*"
RewriteRule "^foo\.html$"         "foo.NS.html"          [L]

RewriteCond "%{HTTP_USER_AGENT}"  "^Lynx/" [OR]
RewriteCond "%{HTTP_USER_AGENT}"  "^Mozilla/[12]"
RewriteRule "^foo\.html$"         "foo.20.html"          [L]

RewriteRule "^foo\.html$"         "foo.32.html"          [L]

Canonical URLs

Description:

On some webservers there is more than one URL for a resource. Usually there are canonical URLs (which are be actually used and distributed) and those which are just shortcuts, internal ones, and so on. Independent of which URL the user supplied with the request, they should finally see the canonical one in their browser address bar.

Solution:

We do an external HTTP redirect for all non-canonical URLs to fix them in the location view of the Browser and for all subsequent requests. In the example ruleset below we replace /puppies and /canines by the canonical /dogs.

RewriteRule   "^/(puppies|canines)/(.*)"    "/dogs/$2"  [R]
Discussion:
This should really be accomplished with Redirect or RedirectMatch directives:
RedirectMatch "^/(puppies|canines)/(.*)" "/dogs/$2"

Moved DocumentRoot

Description:

Usually the DocumentRoot of the webserver directly relates to the URL "/". But often this data is not really of top-level priority. For example, you may wish for visitors, on first entering a site, to go to a particular subdirectory /about/. This may be accomplished using the following ruleset:

Solution:

We redirect the URL / to /about/:

RewriteEngine on
RewriteRule   "^/$"  "/about/"  [R]

Note that this can also be handled using the RedirectMatch directive:

RedirectMatch "^/$" "http://example.com/about/"

Note also that the example rewrites only the root URL. That is, it rewrites a request for http://example.com/, but not a request for http://example.com/page.html. If you have in fact changed your document root - that is, if all of your content is in fact in that subdirectory, it is greatly preferable to simply change your DocumentRoot directive, or move all of the content up one directory, rather than rewriting URLs.

Fallback Resource

Description:
You want a single resource (say, a certain file, like index.php) to handle all requests that come to a particular directory, except those that should go to an existing resource such as an image, or a css file.
Solution:

As of version 2.2.16, you should use the FallbackResource directive for this:

<Directory "/var/www/my_blog">
  FallbackResource "index.php"
</Directory>

However, in earlier versions of Apache, or if your needs are more complicated than this, you can use a variation of the following rewrite set to accomplish the same thing:

<Directory "/var/www/my_blog">
  RewriteBase "/my_blog"

  RewriteCond "/var/www/my_blog/%{REQUEST_FILENAME}" !-f
  RewriteCond "/var/www/my_blog/%{REQUEST_FILENAME}" !-d
  RewriteRule "^" "index.php" [PT]
</Directory>

If, on the other hand, you wish to pass the requested URI as a query string argument to index.php, you can replace that RewriteRule with:

RewriteRule "(.*)" "index.php?$1" [PT,QSA]

Note that these rulesets can be used in a .htaccess file, as well as in a <Directory> block.

Rewrite query string

Description:
You want to capture a particular value from a query string and either replace it or incorporate it into another component of the URL.
Solutions:

Many of the solutions in this section will all use the same condition, which leaves the matched value in the %2 backreference. %1 is the beginining of the query string (up to the key of intererest), and %3 is the remainder. This condition is a bit complex for flexibility and to avoid double '&&' in the substitutions.

  • This solution removes the matching key and value:
    # Remove mykey=???
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$"
RewriteRule "(.*)" "$1?%1%3"
  • This solution uses the captured value in the URL subsitution, discarding the rest of the original query by appending a '?':
    # Copy from query string to PATH_INFO
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$"
RewriteRule "(.*)" "$1/products/%2/?" [PT]
  • This solution checks the captured value in a subsequent condition:
    # Capture the value of mykey in the query string
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$"
RewriteCond "%2" !=not-so-secret-value
RewriteRule "(.*)" - [F]
  • This solution shows the reverse of the previous ones, copying path components (perhaps PATH_INFO) from the URL into the query string.
    # The desired URL might be /products/kitchen-sink, and the script expects
# /path?products=kitchen-sink.
RewriteRule "^/?path/([^/]+)/([^/]+)" "/path?$1=$2" [PT]


Using mod_rewrite to control access - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Using mod_rewrite to control access

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to control access to various resources, and other related techniques. This includes many examples of common uses of mod_rewrite, including detailed descriptions of how each works.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Forbidding Image "Hotlinking"

Description:

The following technique forbids the practice of other sites including your images inline in their pages. This practice is often referred to as "hotlinking", and results in your bandwidth being used to serve content for someone else's site.

Solution:

This technique relies on the value of the HTTP_REFERER variable, which is optional. As such, it's possible for some people to circumvent this limitation. However, most users will experience the failed request, which should, over time, result in the image being removed from that other site.

There are several ways that you can handle this situation.

In this first example, we simply deny the request, if it didn't initiate from a page on our site. For the purpose of this example, we assume that our site is www.example.com.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$"    "-"   [F,NC]

In this second example, instead of failing the request, we display an alternate image instead.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$"    "/images/go-away.png"   [R,NC]

In the third example, we redirect the request to an image on some other site.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$" "http://other.example.com/image.gif"   [R,NC]

Of these techniques, the last two tend to be the most effective in getting people to stop hotlinking your images, because they will simply not see the image that they expected to see.

Discussion:

If all you wish to do is deny access to the resource, rather than redirecting that request elsewhere, this can be accomplished without the use of mod_rewrite:

SetEnvIf Referer "example\.com" localreferer
<FilesMatch "\.(jpg|png|gif)$">
    Require env localreferer
</FilesMatch>

Blocking of Robots

Description:

In this recipe, we discuss how to block persistent requests from a particular robot, or user agent.

The standard for robot exclusion defines a file, /robots.txt that specifies those portions of your website where you wish to exclude robots. However, some robots do not honor these files.

Note that there are methods of accomplishing this which do not use mod_rewrite. Note also that any technique that relies on the clients USER_AGENT string can be circumvented very easily, since that string can be changed.

Solution:

We use a ruleset that specifies the directory to be protected, and the client USER_AGENT that identifies the malicious or persistent robot.

In this example, we are blocking a robot called NameOfBadRobot from a location /secret/files. You may also specify an IP address range, if you are trying to block that user agent only from the particular source.

RewriteCond "%{HTTP_USER_AGENT}"   "^NameOfBadRobot"
RewriteCond "%{REMOTE_ADDR}"       "=123\.45\.67\.[8-9]"
RewriteRule "^/secret/files/"   "-"   [F]
Discussion:

Rather than using mod_rewrite for this, you can accomplish the same end using alternate means, as illustrated here:

SetEnvIfNoCase User-Agent "^NameOfBadRobot" goaway
<Location "/secret/files">
    <RequireAll>
        Require all granted
        Require not env goaway
    </RequireAll>
</Location>

As noted above, this technique is trivial to circumvent, by simply modifying the USER_AGENT request header. If you are experiencing a sustained attack, you should consider blocking it at a higher level, such as at your firewall.

Denying Hosts in a Blacklist

Description:

We wish to maintain a blacklist of hosts, rather like hosts.deny, and have those hosts blocked from accessing our server.

Solution:
RewriteEngine on
RewriteMap    hosts-deny  "txt:/path/to/hosts.deny"
RewriteCond   "${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}" "!=NOT-FOUND" [OR]
RewriteCond   "${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}" "!=NOT-FOUND"
RewriteRule   "^"  "-"  [F]

##
## hosts.deny
##
## ATTENTION! This is a map, not a list, even when we treat it as such.
## mod_rewrite parses it for key/value pairs, so at least a
## dummy value "-" must be present for each entry.
##

193.102.180.41 -
bsdti1.sdm.de -
192.76.162.40 -

Discussion:

The second RewriteCond assumes that you have HostNameLookups turned on, so that client IP addresses will be resolved. If that's not the case, you should drop the second RewriteCond, and drop the [OR] flag from the first RewriteCond.

Referer-based Deflector

Description:

Redirect requests based on the Referer from which the request came, with different targets per Referer.

Solution:

The following ruleset uses a map file to associate each Referer with a redirection target.

RewriteMap  deflector "txt:/path/to/deflector.map"

RewriteCond "%{HTTP_REFERER}" !=""
RewriteCond "${deflector:%{HTTP_REFERER}}" "=-"
RewriteRule "^" "%{HTTP_REFERER}" [R,L]

RewriteCond "%{HTTP_REFERER}" !=""
RewriteCond "${deflector:%{HTTP_REFERER}|NOT-FOUND}" "!=NOT-FOUND"
RewriteRule "^" "${deflector:%{HTTP_REFERER}}" [R,L]

The map file lists redirection targets for each referer, or, if we just wish to redirect back to where they came from, a "-" is placed in the map:

##

##  deflector.map

##

http://badguys.example.com/bad/index.html    -

http://badguys.example.com/bad/index2.html   -

http://badguys.example.com/bad/index3.html   http://somewhere.example.com/


Dynamic mass virtual hosts with mod_rewrite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Dynamic mass virtual hosts with mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to create dynamically configured virtual hosts.

mod_rewrite is not the best way to configure virtual hosts. You should first consider the alternatives before resorting to mod_rewrite. See also the "how to avoid mod_rewrite document.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Proxying
  • RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Virtual Hosts For Arbitrary Hostnames

Description:

We want to automatically create a virtual host for every hostname which resolves in our domain, without having to create new VirtualHost sections.

In this recipe, we assume that we'll be using the hostname www.SITE.example.com for each user, and serve their content out of /home/SITE/www.

Solution:
RewriteEngine on

RewriteMap    lowercase int:tolower

RewriteCond   "${lowercase:%{HTTP_HOST}}"   "^www\.([^.]+)\.example\.com$"
RewriteRule   "^(.*)" "/home/%1/www$1"
Discussion
You will need to take care of the DNS resolution - Apache does not handle name resolution. You'll need either to create CNAME records for each hostname, or a DNS wildcard record. Creating DNS records is beyond the scope of this document.

The internal tolower RewriteMap directive is used to ensure that the hostnames being used are all lowercase, so that there is no ambiguity in the directory structure which must be created.

Parentheses used in a RewriteCond are captured into the backreferences %1, %2, etc, while parentheses used in RewriteRule are captured into the backreferences $1, $2, etc.

As with many techniques discussed in this document, mod_rewrite really isn't the best way to accomplish this task. You should, instead, consider using mod_vhost_alias instead, as it will much more gracefully handle anything beyond serving static files, such as any dynamic content, and Alias resolution.

Dynamic Virtual Hosts Using mod_rewrite

This extract from httpd.conf does the same thing as the first example. The first half is very similar to the corresponding part above, except for some changes, required for backward compatibility and to make the mod_rewrite part work properly; the second half configures mod_rewrite to do the actual work.

Because mod_rewrite runs before other URI translation modules (e.g., mod_alias), mod_rewrite must be told to explicitly ignore any URLs that would have been handled by those modules. And, because these rules would otherwise bypass any ScriptAlias directives, we must have mod_rewrite explicitly enact those mappings.

# get the server name from the Host: header
UseCanonicalName Off

# splittable logs
LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

<Directory "/www/hosts">
    # ExecCGI is needed here because we can't force
    # CGI execution in the way that ScriptAlias does
    Options FollowSymLinks ExecCGI
</Directory>

RewriteEngine On

# a ServerName derived from a Host: header may be any case at all
RewriteMap  lowercase  int:tolower

## deal with normal documents first:
# allow Alias "/icons/" to work - repeat for other aliases
RewriteCond  "%{REQUEST_URI}"  "!^/icons/"
# allow CGIs to work
RewriteCond  "%{REQUEST_URI}"  "!^/cgi-bin/"
# do the magic
RewriteRule  "^/(.*)$"  "/www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1"

## and now deal with CGIs - we have to force a handler
RewriteCond  "%{REQUEST_URI}"  "^/cgi-bin/"
RewriteRule  "^/(.*)$"  "/www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1"  [H=cgi-script]

Using a Separate Virtual Host Configuration File

This arrangement uses more advanced mod_rewrite features to work out the translation from virtual host to document root, from a separate configuration file. This provides more flexibility, but requires more complicated configuration.

The vhost.map file should look something like this:

customer-1.example.com /www/customers/1
customer-2.example.com /www/customers/2
# ...
customer-N.example.com /www/customers/N

The httpd.conf should contain the following:

RewriteEngine on

RewriteMap   lowercase  int:tolower

# define the map file
RewriteMap   vhost      "txt:/www/conf/vhost.map"

# deal with aliases as above
RewriteCond  "%{REQUEST_URI}"               "!^/icons/"
RewriteCond  "%{REQUEST_URI}"               "!^/cgi-bin/"
RewriteCond  "${lowercase:%{SERVER_NAME}}"  "^(.+)$"
# this does the file-based remap
RewriteCond  "${vhost:%1}"                  "^(/.*)$"
RewriteRule  "^/(.*)$"                      "%1/docs/$1"

RewriteCond  "%{REQUEST_URI}"               "^/cgi-bin/"
RewriteCond  "${lowercase:%{SERVER_NAME}}"  "^(.+)$"
RewriteCond  "${vhost:%1}"                  "^(/.*)$"
RewriteRule  "^/(.*)$"                      "%1/cgi-bin/$1" [H=cgi-script]


Using mod_rewrite for Proxying - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Using mod_rewrite for Proxying

This document supplements the mod_rewrite reference documentation. It describes how to use the RewriteRule's [P] flag to proxy content to another server. A number of recipes are provided that describe common scenarios.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Proxying Content with mod_rewrite

Description:

mod_rewrite provides the [P] flag, which allows URLs to be passed, via mod_proxy, to another server. Two examples are given here. In one example, a URL is passed directly to another server, and served as though it were a local URL. In the other example, we proxy missing content to a back-end server.

Solution:

To simply map a URL to another server, we use the [P] flag, as follows:

RewriteEngine  on
RewriteBase    "/products/"
RewriteRule    "^widget/(.*)$"  "http://product.example.com/widget/$1"  [P]
ProxyPassReverse "/products/widget/" "http://product.example.com/widget/"

In the second example, we proxy the request only if we can't find the resource locally. This can be very useful when you're migrating from one server to another, and you're not sure if all the content has been migrated yet.

RewriteCond "%{REQUEST_FILENAME}"       !-f
RewriteCond "%{REQUEST_FILENAME}"       !-d
RewriteRule "^/(.*)" "http://old.example.com/$1" [P]
ProxyPassReverse "/" "http://old.example.com/"
Discussion:

In each case, we add a ProxyPassReverse directive to ensure that any redirects issued by the backend are correctly passed on to the client.

Consider using either ProxyPass or ProxyPassMatch whenever possible in preference to mod_rewrite.


Using RewriteMap - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Using RewriteMap

This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, and provides examples of each of the various RewriteMap types.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Advanced techniques
  • When not to use mod_rewrite

Introduction

The RewriteMap directive defines an external function which can be called in the context of RewriteRule or RewriteCond directives to perform rewriting that is too complicated, or too specialized to be performed just by regular expressions. The source of this lookup can be any of the types listed in the sections below, and enumerated in the RewriteMap reference documentation.

The syntax of the RewriteMap directive is as follows:

RewriteMap MapName MapType:MapSource

The MapName is an arbitray name that you assign to the map, and which you will use in directives later on. Arguments are passed to the map via the following syntax:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

For example, you might define a RewriteMap as:

RewriteMap examplemap "txt:/path/to/file/map.txt"

You would then be able to use this map in a RewriteRule as follows:

RewriteRule "^/ex/(.*)" "${examplemap:$1}"

A default value can be specified in the event that nothing is found in the map:

RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"

Per-directory and .htaccess context

The RewriteMap directive may not be used in <Directory> sections or .htaccess files. You must declare the map in server or virtualhost context. You may use the map, once created, in your RewriteRule and RewriteCond directives in those scopes. You just can't declare it in those scopes.

The sections that follow describe the various MapTypes that may be used, and give examples of each.

txt: Plain text maps

When a MapType of txt is used, the MapSource is a filesystem path to a plain-text mapping file, containing space-separated key/value pair per line. Optionally, a line may be contain a comment, starting with a '#' character.

For example, the following might be valid entries in a map file.

# Comment line
MatchingKey SubstValue
MatchingKey SubstValue # comment

When the RewriteMap is invoked the argument is looked for in the first argument of a line, and, if found, the substitution value is returned.

For example, we might use a mapfile to translate product names to product IDs for easier-to-remember URLs, using the following recipe:

Product to ID configuration

RewriteMap product2id "txt:/etc/apache2/productmap.txt"
RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

We assume here that the prods.php script knows what to do when it received an argument of id=NOTFOUND when a product is not found in the lookup map.

The file /etc/apache2/productmap.txt then contains the following:

Product to ID map

##
## productmap.txt - Product to ID map file
##

television 993
stereo 198
fishingrod 043
basketball 418
telephone 328

Thus, when http://example.com/product/television is requested, the RewriteRule is applied, and the request is internally mapped to /prods.php?id=993.

Note: .htaccess files

The example given is crafted to be used in server or virtualhost scope. If you're planning to use this in a .htaccess file, you'll need to remove the leading slash from the rewrite pattern in order for it to match anything:
RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

Cached lookups

The looked-up keys are cached by httpd until the mtime (modified time) of the mapfile changes, or the httpd server is restarted. This ensures better performance on maps that are called by many requests.

rnd: Randomized Plain Text

When a MapType of rnd is used, the MapSource is a filesystem path to a plain-text mapping file, each line of which contains a key, and one or more values separated by |. One of these values will be chosen at random if the key is matched.

For example, you might use the following map file and directives to provide a random load balancing between several back-end servers, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything else is sent to one of the 'dynamic' pool.

Rewrite map file

##
## map.txt -- rewriting map
##

static www1|www2|www3|www4
dynamic www5|www6

Configuration directives

RewriteMap servers "rnd:/path/to/file/map.txt"

RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]

So, when an image is requested and the first of these rules is matched, RewriteMap looks up the string static in the map file, which returns one of the specified hostnames at random, which is then used in the RewriteRule target.

If you wanted to have one of the servers more likely to be chosen (for example, if one of the server has more memory than the others, and so can handle more requests) simply list it more times in the map file.

static www1|www1|www2|www3|www4

dbm: DBM Hash File

When a MapType of dbm is used, the MapSource is a filesystem path to a DBM database file containing key/value pairs to be used in the mapping. This works exactly the same way as the txt map, but is much faster, because a DBM is indexed, whereas a text file is not. This allows more rapid access to the desired key.

You may optionally specify a particular dbm type:

RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"

The type can be sdbm, gdbm, ndbm or db. However, it is recommended that you just use the httxt2dbm utility that is provided with Apache HTTP Server, as it will use the correct DBM library, matching the one that was used when httpd itself was built.

To create a dbm file, first create a text map file as described in the txt section. Then run httxt2dbm:

$ httxt2dbm -i mapfile.txt -o mapfile.map

You can then reference the resulting file in your RewriteMap directive:

RewriteMap mapname "dbm:/etc/apache/mapfile.map"

Note that with some dbm types, more than one file is generated, with a common base name. For example, you may have two files named mapfile.map.dir and mapfiile.map.pag. This is normal, and you need only use the base name mapfile.map in your RewriteMap directive.

Cached lookups

The looked-up keys are cached by httpd until the mtime (modified time) of the mapfile changes, or the httpd server is restarted. This ensures better performance on maps that are called by many requests.

int: Internal Function

When a MapType of int is used, the MapSource is one of the available internal RewriteMap functions. Module authors can provide additional internal functions by registering them with the ap_register_rewrite_mapfunc API. The functions that are provided by default are:

  • toupper:
    Converts the key to all upper case.
  • tolower:
    Converts the key to all lower case.
  • escape:
    Translates special characters in the key to hex-encodings.
  • unescape:
    Translates hex-encodings in the key back to special characters.

To use one of these functions, create a RewriteMap referencing the int function, and then use that in your RewriteRule:

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower
RewriteRule "(.*)" "${lc:$1}" [R]

Please note that the example offered here is for illustration purposes only, and is not a recommendation. If you want to make URLs case-insensitive, consider using mod_speling instead.

prg: External Rewriting Program

When a MapType of prg is used, the MapSource is a filesystem path to an executable program which will providing the mapping behavior. This can be a compiled binary file, or a program in an interpreted language such as Perl or Python.

This program is started once, when the Apache HTTP Server is started, and then communicates with the rewriting engine via STDIN and STDOUT. That is, for each map function lookup, it expects one argument via STDIN, and should return one new-line terminated response string on STDOUT. If there is no corresponding lookup value, the map program should return the four-character string "NULL" to indicate this.

External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on.

This feature utilizes the rewrite-map mutex, which is required for reliable communication with the program. The mutex mechanism and lock file can be configured with the Mutex directive.

A simple example is shown here which will replace all dashes with underscores in a request URI.

Rewrite configuration

RewriteMap d2u "prg:/www/bin/dash2under.pl"

RewriteRule "-" "${d2u:%{REQUEST_URI}}"

dash2under.pl

#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
while (<STDIN>) {
    s/-/_/g; # Replace dashes with underscores
    print $_;
}

Caution!

  • Keep your rewrite map program as simple as possible. If the program hangs, it will cause httpd to wait indefinitely for a response from the map, which will, in turn, cause httpd to stop responding to requests.
  • Be sure to turn off buffering in your program. In Perl this is done by the second line in the example script: $| = 1; This will of course vary in other languages. Buffered I/O will cause httpd to wait for the output, and so it will hang.
  • Remember that there is only one copy of the program, started at server startup. All requests will need to go through this one bottleneck. This can cause significant slowdowns if many requests must go through this process, or if the script itself is very slow.

dbd or fastdbd: SQL Query

When a MapType of dbd or fastdbd is used, the MapSource is a SQL SELECT statement that takes a single argument and returns a single value.

mod_dbd will need to be configured to point at the right database for this statement to be executed.

There are two forms of this MapType. Using a MapType of dbd causes the query to be executed with each map request, while using fastdbd caches the database lookups internally. So, while fastdbd is more efficient, and therefore faster, it won't pick up on changes to the database until the server is restarted.

If a query returns more than one row, a random row from the result set is used.

Example

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

Summary

The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its rewriting mapfile.

While you cannot declare a map in per-directory context (.htaccess files or <Directory> blocks) it is possible to use this map in per-directory context.


Advanced Techniques with mod_rewrite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Advanced Techniques with mod_rewrite

This document supplements the mod_rewrite reference documentation. It provides a few advanced techniques using mod_rewrite.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • When not to use mod_rewrite

URL-based sharding across multiple backends

Description:

A common technique for distributing the burden of server load or storage space is called "sharding". When using this method, a front-end server will use the url to consistently "shard" users or objects to separate backend servers.

Solution:

A mapping is maintained, from users to target servers, in external map files. They look like:

user1 physical_host_of_user1
user2 physical_host_of_user2
: :

We put this into a map.users-to-hosts file. The aim is to map;

/u/user1/anypath

to

http://physical_host_of_user1/u/user/anypath

thus every URL path need not be valid on every backend physical host. The following ruleset does this for us with the help of the map files assuming that server0 is a default server which will be used if a user has no entry in the map:

RewriteEngine on
RewriteMap      users-to-hosts   "txt:/path/to/map.users-to-hosts"
RewriteRule   "^/u/([^/]+)/?(.*)"   "http://${users-to-hosts:$1|server0}/u/$1/$2"

See the RewriteMap documentation for more discussion of the syntax of this directive.

On-the-fly Content-Regeneration

Description:

We wish to dynamically generate content, but store it statically once it is generated. This rule will check for the existence of the static file, and if it's not there, generate it. The static files can be removed periodically, if desired (say, via cron) and will be regenerated on demand.

Solution:
This is done via the following ruleset:
# This example is valid in per-directory context only
RewriteCond "%{REQUEST_URI}"   "!-U"
RewriteRule "^(.+)\.html$"          "/regenerate_page.cgi"   [PT,L]

The -U operator determines whether the test string (in this case, REQUEST_URI) is a valid URL. It does this via a subrequest. In the event that this subrequest fails - that is, the requested resource doesn't exist - this rule invokes the CGI program /regenerate_page.cgi, which generates the requested resource and saves it into the document directory, so that the next time it is requested, a static copy can be served.

In this way, documents that are infrequently updated can be served in static form. if documents need to be refreshed, they can be deleted from the document directory, and they will then be regenerated the next time they are requested.

Load Balancing

Description:

We wish to randomly distribute load across several servers using mod_rewrite.

Solution:

We'll use RewriteMap and a list of servers to accomplish this.

RewriteEngine on
RewriteMap lb "rnd:/path/to/serverlist.txt"
RewriteRule "^/(.*)" "http://${lb:servers}/$1" [P,L]

serverlist.txt will contain a list of the servers:

## serverlist.txt

servers one.example.com|two.example.com|three.example.com

If you want one particular server to get more of the load than the others, add it more times to the list.

Discussion

Apache comes with a load-balancing module - mod_proxy_balancer - which is far more flexible and featureful than anything you can cobble together using mod_rewrite.

Structured Userdirs

Description:

Some sites with thousands of users use a structured homedir layout, i.e. each homedir is in a subdirectory which begins (for instance) with the first character of the username. So, /~larry/anypath is /home/l/larry/public_html/anypath while /~waldo/anypath is /home/w/waldo/public_html/anypath.

Solution:

We use the following ruleset to expand the tilde URLs into the above layout.

RewriteEngine on
RewriteRule   "^/~(([a-z])[a-z0-9]+)(.*)"  "/home/$2/$1/public_html$3"

Redirecting Anchors

Description:

By default, redirecting to an HTML anchor doesn't work, because mod_rewrite escapes the # character, turning it into %23. This, in turn, breaks the redirection.

Solution:

Use the [NE] flag on the RewriteRule. NE stands for No Escape.

Discussion:
This technique will of course also work with other special characters that mod_rewrite, by default, URL-encodes.

Time-Dependent Rewriting

Description:

We wish to use mod_rewrite to serve different content based on the time of day.

Solution:

There are a lot of variables named TIME_xxx for rewrite conditions. In conjunction with the special lexicographic comparison patterns <STRING, >STRING and =STRING we can do time-dependent redirects:

RewriteEngine on
RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" ">0700"
RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" "<1900"
RewriteRule   "^foo\.html$"             "foo.day.html" [L]
RewriteRule   "^foo\.html$"             "foo.night.html"

This provides the content of foo.day.html under the URL foo.html from 07:01-18:59 and at the remaining time the contents of foo.night.html.

mod_cache, intermediate proxies and browsers may each cache responses and cause the either page to be shown outside of the time-window configured. mod_expires may be used to control this effect. You are, of course, much better off simply serving the content dynamically, and customizing it based on the time of day.

Set Environment Variables Based On URL Parts

Description:

At time, we want to maintain some kind of status when we perform a rewrite. For example, you want to make a note that you've done that rewrite, so that you can check later to see if a request can via that rewrite. One way to do this is by setting an environment variable.

Solution:

Use the [E] flag to set an environment variable.

RewriteEngine on
RewriteRule   "^/horse/(.*)"   "/pony/$1" [E=rewritten:1]

Later in your ruleset you might check for this environment variable using a RewriteCond:

RewriteCond "%{ENV:rewritten}" "=1"

Note that environment variables do not survive an external redirect. You might consider using the [CO] flag to set a cookie.


When not to use mod_rewrite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

When not to use mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes perhaps one of the most important concepts about mod_rewrite - namely, when to avoid using it.

mod_rewrite should be considered a last resort, when other alternatives are found wanting. Using it when there are simpler alternatives leads to configurations which are confusing, fragile, and hard to maintain. Understanding what other alternatives are available is a very important step towards mod_rewrite mastery.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

The most common situation in which mod_rewrite is the right tool is when the very best solution requires access to the server configuration files, and you don't have that access. Some configuration directives are only available in the server configuration file. So if you are in a hosting situation where you only have .htaccess files to work with, you may need to resort to mod_rewrite.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques

Simple Redirection

mod_alias provides the Redirect and RedirectMatch directives, which provide a means to redirect one URL to another. This kind of simple redirection of one URL, or a class of URLs, to somewhere else, should be accomplished using these directives rather than RewriteRule. RedirectMatch allows you to include a regular expression in your redirection criteria, providing many of the benefits of using RewriteRule.

A common use for RewriteRule is to redirect an entire class of URLs. For example, all URLs in the /one directory must be redirected to http://one.example.com/, or perhaps all http requests must be redirected to https.

These situations are better handled by the Redirect directive. Remember that Redirect preserves path information. That is to say, a redirect for a URL /one will also redirect all URLs under that, such as /one/two.html and /one/three/four.html.

To redirect URLs under /one to http://one.example.com, do the following:

Redirect "/one/" "http://one.example.com/"

To redirect one hostname to another, for example example.com to www.example.com, see the Canonical Hostnames recipe.

To redirect http URLs to https, do the following:

<VirtualHost *:80>
    ServerName www.example.com
    Redirect "/" "https://www.example.com/"
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.com
    # ... SSL configuration goes here
</VirtualHost>

The use of RewriteRule to perform this task may be appropriate if there are other RewriteRule directives in the same scope. This is because, when there are Redirect and RewriteRule directives in the same scope, the RewriteRule directives will run first, regardless of the order of appearance in the configuration file.

In the case of the http-to-https redirection, the use of RewriteRule would be appropriate if you don't have access to the main server configuration file, and are obliged to perform this task in a .htaccess file instead.

URL Aliasing

The Alias directive provides mapping from a URI to a directory - usually a directory outside of your DocumentRoot. Although it is possible to perform this mapping with mod_rewrite, Alias is the preferred method, for reasons of simplicity and performance.

Using Alias

Alias "/cats" "/var/www/virtualhosts/felines/htdocs"

The use of mod_rewrite to perform this mapping may be appropriate when you do not have access to the server configuration files. Alias may only be used in server or virtualhost context, and not in a .htaccess file.

Symbolic links would be another way to accomplish the same thing, if you have Options FollowSymLinks enabled on your server.

Virtual Hosting

Although it is possible to handle virtual hosts with mod_rewrite, it is seldom the right way. Creating individual <VirtualHost> blocks is almost always the right way to go. In the event that you have an enormous number of virtual hosts, consider using mod_vhost_alias to create these hosts automatically.

Modules such as mod_macro are also useful for creating a large number of virtual hosts dynamically.

Using mod_rewrite for vitualhost creation may be appropriate if you are using a hosting service that does not provide you access to the server configuration files, and you are therefore restricted to configuration using .htaccess files.

See the virtual hosts with mod_rewrite document for more details on how you might accomplish this if it still seems like the right approach.

Simple Proxying

RewriteRule provides the [P] flag to pass rewritten URIs through mod_proxy.

RewriteRule "^/?images(.*)" "http://imageserver.local/images$1" [P]

However, in many cases, when there is no actual pattern matching needed, as in the example shown above, the ProxyPass directive is a better choice. The example here could be rendered as:

ProxyPass "/images/" "http://imageserver.local/images/"

Note that whether you use RewriteRule or ProxyPass, you'll still need to use the ProxyPassReverse directive to catch redirects issued from the back-end server:

ProxyPassReverse "/images/" "http://imageserver.local/images/"

You may need to use RewriteRule instead when there are other RewriteRules in effect in the same scope, as a RewriteRule will usually take effect before a ProxyPass, and so may preempt what you're trying to accomplish.

Environment Variable Testing

mod_rewrite is frequently used to take a particular action based on the presence or absence of a particular environment variable or request header. This can be done more efficiently using the <If>.

Consider, for example, the common scenario where RewriteRule is used to enforce a canonical hostname, such as www.example.com instead of example.com. This can be done using the <If> directive, as shown here:

<If "req('Host') != 'www.example.com'">
    Redirect "/" "http://www.example.com/"
</If>

This technique can be used to take actions based on any request header, response header, or environment variable, replacing mod_rewrite in many common scenarios.

See especially the expression evaluation documentation for a overview of what types of expressions you can use in <If> sections, and in certain other directives.


RewriteRule Flags - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

RewriteRule Flags

This document discusses the flags which are available to the RewriteRule directive, providing detailed explanations and examples.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Introduction

A RewriteRule can have its behavior modified by one or more flags. Flags are included in square brackets at the end of the rule, and multiple flags are separated by commas.

RewriteRule pattern target [Flag1,Flag2,Flag3]

Each flag (with a few exceptions) has a short form, such as CO, as well as a longer form, such as cookie. While it is most common to use the short form, it is recommended that you familiarize yourself with the long form, so that you remember what each flag is supposed to do. Some flags take one or more arguments. Flags are not case sensitive.

Flags that alter metadata associated with the request (T=, H=, E=) have no affect in per-directory and htaccess context, when a substitution (other than '-') is performed during the same round of rewrite processing.

Presented here are each of the available flags, along with an example of how you might use them.

B (escape backreferences)

The [B] flag instructs RewriteRule to escape non-alphanumeric characters before applying the transformation.

mod_rewrite has to unescape URLs before mapping them, so backreferences are unescaped at the time they are applied. Using the B flag, non-alphanumeric characters in backreferences will be escaped. For example, consider the rule:

RewriteRule "^search/(.*)$" "/search.php?term=$1"

Given a search term of 'x & y/z', a browser will encode it as 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B flag, this rewrite rule will map to 'search.php?term=x & y/z', which isn't a valid URL, and so would be encoded as search.php?term=x%20&y%2Fz=, which is not what was intended.

With the B flag set on this same rule, the parameters are re-encoded before being passed on to the output URL, resulting in a correct mapping to /search.php?term=x%20%26%20y%2Fz.

Note that you may also need to set AllowEncodedSlashes to On to get this particular example to work, as httpd does not allow encoded slashes in URLs, and returns a 404 if it sees one.

This escaping is particularly necessary in a proxy situation, when the backend may break if presented with an unescaped URL.

C|chain

The [C] or [chain] flag indicates that the RewriteRule is chained to the next rule. That is, if the rule matches, then it is processed as usual and control moves on to the next rule. However, if it does not match, then the next rule, and any other rules that are chained together, are skipped.

CO|cookie

The [CO], or [cookie] flag, allows you to set a cookie when a particular RewriteRule matches. The argument consists of three required fields and four optional fields.

The full syntax for the flag, including all attributes, is as follows:

[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]

If a literal ':' character is needed in any of the cookie fields, an alternate syntax is available. To opt-in to the alternate syntax, the cookie "Name" should be preceded with a ';' character, and field separators should be specified as ';'.

[CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly]

You must declare a name, a value, and a domain for the cookie to be set.

Domain
The domain for which you want the cookie to be valid. This may be a hostname, such as www.example.com, or it may be a domain, such as .example.com. It must be at least two parts separated by a dot. That is, it may not be merely .com or .net. Cookies of that kind are forbidden by the cookie security model.

You may optionally also set the following values:

Lifetime
The time for which the cookie will persist, in minutes.
A value of 0 indicates that the cookie will persist only for the current browser session. This is the default value if none is specified.
Path
The path, on the current website, for which the cookie is valid, such as /customers/ or /files/download/.
By default, this is set to / - that is, the entire website.
Secure
If set to secure, true, or 1, the cookie will only be permitted to be translated via secure (https) connections.
httponly
If set to HttpOnly, true, or 1, the cookie will have the HttpOnly flag set, which means that the cookie is inaccessible to JavaScript code on browsers that support this feature.

Consider this example:

RewriteEngine On
RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]

In the example give, the rule doesn't rewrite the request. The "-" rewrite target tells mod_rewrite to pass the request through unchanged. Instead, it sets a cookie called 'frontdoor' to a value of 'yes'. The cookie is valid for any host in the .example.com domain. It is set to expire in 1440 minutes (24 hours) and is returned for all URIs.

DPI|discardpath

The DPI flag causes the PATH_INFO portion of the rewritten URI to be discarded.

This flag is available in version 2.2.12 and later.

In per-directory context, the URI each RewriteRule compares against is the concatenation of the current values of the URI and PATH_INFO.

The current URI can be the initial URI as requested by the client, the result of a previous round of mod_rewrite processing, or the result of a prior rule in the current round of mod_rewrite processing.

In contrast, the PATH_INFO that is appended to the URI before each rule reflects only the value of PATH_INFO before this round of mod_rewrite processing. As a consequence, if large portions of the URI are matched and copied into a substitution in multiple RewriteRule directives, without regard for which parts of the URI came from the current PATH_INFO, the final URI may have multiple copies of PATH_INFO appended to it.

Use this flag on any substitution where the PATH_INFO that resulted from the previous mapping of this request to the filesystem is not of interest. This flag permanently forgets the PATH_INFO established before this round of mod_rewrite processing began. PATH_INFO will not be recalculated until the current round of mod_rewrite processing completes. Subsequent rules during this round of processing will see only the direct result of substitutions, without any PATH_INFO appended.

E|env

With the [E], or [env] flag, you can set the value of an environment variable. Note that some environment variables may be set after the rule is run, thus unsetting what you have set. See the Environment Variables document for more details on how Environment variables work.

The full syntax for this flag is:

[E=VAR:VAL]
[E=!VAR]

VAL may contain backreferences ($N or %N) which are expanded.

Using the short form

[E=VAR]

you can set the environment variable named VAR to an empty value.

The form

[E=!VAR]

allows to unset a previously set environment variable named VAR.

Environment variables can then be used in a variety of contexts, including CGI programs, other RewriteRule directives, or CustomLog directives.

The following example sets an environment variable called 'image' to a value of '1' if the requested URI is an image file. Then, that environment variable is used to exclude those requests from the access log.

RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1]
CustomLog "logs/access_log" combined env=!image

Note that this same effect can be obtained using SetEnvIf. This technique is offered as an example, not as a recommendation.

END

Using the [END] flag terminates not only the current round of rewrite processing (like [L]) but also prevents any subsequent rewrite processing from occurring in per-directory (htaccess) context.

This does not apply to new requests resulting from external redirects.

F|forbidden

Using the [F] flag causes the server to return a 403 Forbidden status code to the client. While the same behavior can be accomplished using the Deny directive, this allows more flexibility in assigning a Forbidden status.

The following rule will forbid .exe files from being downloaded from your server.

RewriteRule "\.exe" "-" [F]

This example uses the "-" syntax for the rewrite target, which means that the requested URI is not modified. There's no reason to rewrite to another URI, if you're going to forbid the request.

When using [F], an [L] is implied - that is, the response is returned immediately, and no further rules are evaluated.

G|gone

The [G] flag forces the server to return a 410 Gone status with the response. This indicates that a resource used to be available, but is no longer available.

As with the [F] flag, you will typically use the "-" syntax for the rewrite target when using the [G] flag:

RewriteRule "oldproduct" "-" [G,NC]

When using [G], an [L] is implied - that is, the response is returned immediately, and no further rules are evaluated.

H|handler

Forces the resulting request to be handled with the specified handler. For example, one might use this to force all files without a file extension to be parsed by the php handler:

RewriteRule "!\." "-" [H=application/x-httpd-php]

The regular expression above - !\. - will match any request that does not contain the literal . character.

This can be also used to force the handler based on some conditions. For example, the following snippet used in per-server context allows .php files to be displayed by mod_php if they are requested with the .phps extension:

RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]

The regular expression above - ^(/source/.+\.php)s$ - will match any request that starts with /source/ followed by 1 or n characters followed by .phps literally. The backreference $1 referrers to the captured match within parenthesis of the regular expression.

L|last

The [L] flag causes mod_rewrite to stop processing the rule set. In most contexts, this means that if the rule matches, no further rules will be processed. This corresponds to the last command in Perl, or the break command in C. Use this flag to indicate that the current rule should be applied immediately without considering further rules.

If you are using RewriteRule in either .htaccess files or in <Directory> sections, it is important to have some understanding of how the rules are processed. The simplified form of this is that once the rules have been processed, the rewritten request is handed back to the URL parsing engine to do what it may with it. It is possible that as the rewritten request is handled, the .htaccess file or <Directory> section may be encountered again, and thus the ruleset may be run again from the start. Most commonly this will happen if one of the rules causes a redirect - either internal or external - causing the request process to start over.

It is therefore important, if you are using RewriteRule directives in one of these contexts, that you take explicit steps to avoid rules looping, and not count solely on the [L] flag to terminate execution of a series of rules, as shown below.

An alternative flag, [END], can be used to terminate not only the current round of rewrite processing but prevent any subsequent rewrite processing from occurring in per-directory (htaccess) context. This does not apply to new requests resulting from external redirects.

The example given here will rewrite any request to index.php, giving the original request as a query string argument to index.php, however, the RewriteCond ensures that if the request is already for index.php, the RewriteRule will be skipped.

RewriteBase "/"
RewriteCond "%{REQUEST_URI}" "!=/index.php"
RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]

N|next

The [N] flag causes the ruleset to start over again from the top, using the result of the ruleset so far as a starting point. Use with extreme caution, as it may result in loop.

The [Next] flag could be used, for example, if you wished to replace a certain string or letter repeatedly in a request. The example shown here will replace A with B everywhere in a request, and will continue doing so until there are no more As to be replaced.

RewriteRule "(.*)A(.*)" "$1B$2" [N]

You can think of this as a while loop: While this pattern still matches (i.e., while the URI still contains an A), perform this substitution (i.e., replace the A with a B).

In 2.4.8 and later, this module returns an error after 32,000 iterations to protect against unintended looping. An alternative maximum number of iterations can be specified by adding to the N flag.

# Be willing to replace 1 character in each pass of the loop
RewriteRule "(.+)[><;]$" "$1" [N=64000]
# ... or, give up if after 10 loops
RewriteRule "(.+)[><;]$" "$1" [N=10]

NC|nocase

Use of the [NC] flag causes the RewriteRule to be matched in a case-insensitive manner. That is, it doesn't care whether letters appear as upper-case or lower-case in the matched URI.

In the example below, any request for an image file will be proxied to your dedicated image server. The match is case-insensitive, so that .jpg and .JPG files are both acceptable, for example.

RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]

NE|noescape

By default, special characters, such as & and ?, for example, will be converted to their hexcode equivalent. Using the [NE] flag prevents that from happening.

RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]

The above example will redirect /anchor/xyz to /bigpage.html#xyz. Omitting the [NE] will result in the # being converted to its hexcode equivalent, %23, which will then result in a 404 Not Found error condition.

NS|nosubreq

Use of the [NS] flag prevents the rule from being used on subrequests. For example, a page which is included using an SSI (Server Side Include) is a subrequest, and you may want to avoid rewrites happening on those subrequests. Also, when mod_dir tries to find out information about possible directory default files (such as index.html files), this is an internal subrequest, and you often want to avoid rewrites on such subrequests. On subrequests, it is not always useful, and can even cause errors, if the complete set of rules are applied. Use this flag to exclude problematic rules.

To decide whether or not to use this rule: if you prefix URLs with CGI-scripts, to force them to be processed by the CGI-script, it's likely that you will run into problems (or significant overhead) on sub-requests. In these cases, use this flag.

Images, javascript files, or css files, loaded as part of an HTML page, are not subrequests - the browser requests them as separate HTTP requests.

P|proxy

Use of the [P] flag causes the request to be handled by mod_proxy, and handled via a proxy request. For example, if you wanted all image requests to be handled by a back-end image server, you might do something like the following:

RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]

Use of the [P] flag implies [L] - that is, the request is immediately pushed through the proxy, and any following rules will not be considered.

You must make sure that the substitution string is a valid URI (typically starting with http://hostname) which can be handled by the mod_proxy. If not, you will get an error from the proxy module. Use this flag to achieve a more powerful implementation of the ProxyPass directive, to map remote content into the namespace of the local server.

Security Warning

Take care when constructing the target URL of the rule, considering the security impact from allowing the client influence over the set of URLs to which your server will act as a proxy. Ensure that the scheme and hostname part of the URL is either fixed, or does not allow the client undue influence.

Performance warning

Using this flag triggers the use of mod_proxy, without handling of persistent connections. This means the performance of your proxy will be better if you set it up with ProxyPass or ProxyPassMatch

This is because this flag triggers the use of the default worker, which does not handle connection pooling.

Avoid using this flag and prefer those directives, whenever you can.

Note: mod_proxy must be enabled in order to use this flag.

PT|passthrough

The target (or substitution string) in a RewriteRule is assumed to be a file path, by default. The use of the [PT] flag causes it to be treated as a URI instead. That is to say, the use of the [PT] flag causes the result of the RewriteRule to be passed back through URL mapping, so that location-based mappings, such as Alias, Redirect, or ScriptAlias, for example, might have a chance to take effect.

If, for example, you have an Alias for /icons, and have a RewriteRule pointing there, you should use the [PT] flag to ensure that the Alias is evaluated.

Alias "/icons" "/usr/local/apache/icons"
RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]

Omission of the [PT] flag in this case will cause the Alias to be ignored, resulting in a 'File not found' error being returned.

The PT flag implies the L flag: rewriting will be stopped in order to pass the request to the next phase of processing.

Note that the PT flag is implied in per-directory contexts such as <Directory> sections or in .htaccess files. The only way to circumvent that is to rewrite to -.

QSA|qsappend

When the replacement URI contains a query string, the default behavior of RewriteRule is to discard the existing query string, and replace it with the newly generated one. Using the [QSA] flag causes the query strings to be combined.

Consider the following rule:

RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]

With the [QSA] flag, a request for /pages/123?one=two will be mapped to /page.php?page=123&one=two. Without the [QSA] flag, that same request will be mapped to /page.php?page=123 - that is, the existing query string will be discarded.

QSD|qsdiscard

When the requested URI contains a query string, and the target URI does not, the default behavior of RewriteRule is to copy that query string to the target URI. Using the [QSD] flag causes the query string to be discarded.

This flag is available in version 2.4.0 and later.

Using [QSD] and [QSA] together will result in [QSD] taking precedence.

If the target URI has a query string, the default behavior will be observed - that is, the original query string will be discarded and replaced with the query string in the RewriteRule target URI.

QSL|qslast

By default, the first (left-most) question mark in the substitution delimits the path from the query string. Using the [QSL] flag instructs RewriteRule to instead split the two components using the last (right-most) question mark.

This is useful when mapping to files that have literal question marks in their filename. If no query string is used in the substitution, a question mark can be appended to it in combination with this flag.

This flag is available in version 2.4.19 and later.

R|redirect

Use of the [R] flag causes a HTTP redirect to be issued to the browser. If a fully-qualified URL is specified (that is, including http://servername/) then a redirect will be issued to that location. Otherwise, the current protocol, servername, and port number will be used to generate the URL sent with the redirect.

Any valid HTTP response status code may be specified, using the syntax [R=305], with a 302 status code being used by default if none is specified. The status code specified need not necessarily be a redirect (3xx) status code. However, if a status code is outside the redirect range (300-399) then the substitution string is dropped entirely, and rewriting is stopped as if the L were used.

In addition to response status codes, you may also specify redirect status using their symbolic names: temp (default), permanent, or seeother.

You will almost always want to use [R] in conjunction with [L] (that is, use [R,L]) because on its own, the [R] flag prepends http://thishost[:thisport] to the URI, but then passes this on to the next rule in the ruleset, which can often result in 'Invalid URI in request' warnings.

S|skip

The [S] flag is used to skip rules that you don't want to run. The syntax of the skip flag is [S=N], where N signifies the number of rules to skip (provided the RewriteRule matches). This can be thought of as a goto statement in your rewrite ruleset. In the following example, we only want to run the RewriteRule if the requested URI doesn't correspond with an actual file.

# Is the request for a non-existent file?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# If so, skip these two RewriteRules
RewriteRule ".?" "-" [S=2]

RewriteRule "(.*\.gif)" "images.php?$1"
RewriteRule "(.*\.html)" "docs.php?$1"

This technique is useful because a RewriteCond only applies to the RewriteRule immediately following it. Thus, if you want to make a RewriteCond apply to several RewriteRules, one possible technique is to negate those conditions and add a RewriteRule with a [Skip] flag. You can use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes skip=N, where N is the number of rules in the else-clause:

# Does the file exist?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
RewriteRule ".?" "-" [S=3]

# IF the file exists, then:
    RewriteRule "(.*\.gif)" "images.php?$1"
    RewriteRule "(.*\.html)" "docs.php?$1"
    # Skip past the "else" stanza.
    RewriteRule ".?" "-" [S=1]
# ELSE...
    RewriteRule "(.*)" "404.php?file=$1"
# END

It is probably easier to accomplish this kind of configuration using the <If>, <ElseIf>, and <Else> directives instead.

T|type

Sets the MIME type with which the resulting response will be sent. This has the same effect as the AddType directive.

For example, you might use the following technique to serve Perl source code as plain text, if requested in a particular way:

# Serve .pl files as plain text
RewriteRule "\.pl$" "-" [T=text/plain]

Or, perhaps, if you have a camera that produces jpeg images without file extensions, you could force those images to be served with the correct MIME type by virtue of their file names:

# Files with 'IMG' in the name are jpg images.
RewriteRule "IMG" "-" [T=image/jpg]

Please note that this is a trivial example, and could be better done using <FilesMatch> instead. Always consider the alternate solutions to a problem before resorting to rewrite, which will invariably be a less efficient solution than the alternatives.

If used in per-directory context, use only - (dash) as the substitution for the entire round of mod_rewrite processing, otherwise the MIME-type set with this flag is lost due to an internal re-processing (including subsequent rounds of mod_rewrite processing). The L flag can be useful in this context to end the current round of mod_rewrite processing.


Apache mod_rewrite Technical Details - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Rewrite

Apache mod_rewrite Technical Details

This document discusses some of the technical details of mod_rewrite and URL matching.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

API Phases

The Apache HTTP Server handles requests in several phases. At each of these phases, one or more modules may be called upon to handle that portion of the request lifecycle. Phases include things like URL-to-filename translation, authentication, authorization, content, and logging. (This is not an exhaustive list.)

mod_rewrite acts in two of these phases (or "hooks", as they are often called) to influence how URLs may be rewritten.

First, it uses the URL-to-filename translation hook, which occurs after the HTTP request has been read, but before any authorization starts. Secondly, it uses the Fixup hook, which is after the authorization phases, and after per-directory configuration files (.htaccess files) have been read, but before the content handler is called.

So, after a request comes in and a corresponding server or virtual host has been determined, the rewriting engine starts processing any mod_rewrite directives appearing in the per-server configuration. (i.e., in the main server configuration file and <Virtualhost> sections.) This happens in the URL-to-filename phase.

A few steps later, once the final data directories have been found, the per-directory configuration directives (.htaccess files and <Directory> blocks) are applied. This happens in the Fixup phase.

In each of these cases, mod_rewrite rewrites the REQUEST_URI either to a new URL, or to a filename.

In per-directory context (i.e., within .htaccess files and Directory blocks), these rules are being applied after a URL has already been translated to a filename. Because of this, the URL-path that mod_rewrite initially compares RewriteRule directives against is the full filesystem path to the translated filename with the current directories path (including a trailing slash) removed from the front.

To illustrate: If rules are in /var/www/foo/.htaccess and a request for /foo/bar/baz is being processed, an expression like ^bar/baz$ would match.

If a substitution is made in per-directory context, a new internal subrequest is issued with the new URL, which restarts processing of the request phases. If the substitution is a relative path, the RewriteBase directive determines the URL-path prefix prepended to the substitution. In per-directory context, care must be taken to create rules which will eventually (in some future "round" of per-directory rewrite processing) not perform a substitution to avoid looping. (See RewriteLooping for further discussion of this problem.)

Because of this further manipulation of the URL in per-directory context, you'll need to take care to craft your rewrite rules differently in that context. In particular, remember that the leading directory path will be stripped off of the URL that your rewrite rules will see. Consider the examples below for further clarification.

Location of rule | Rule
VirtualHost section | RewriteRule "^/images/(.+)\.jpg" "/images/$1.gif"
.htaccess file in document root | RewriteRule "^images/(.+)\.jpg" "images/$1.gif"
.htaccess file in images directory | RewriteRule "^(.+)\.jpg" "$1.gif"

For even more insight into how mod_rewrite manipulates URLs in different contexts, you should consult the log entries made during rewriting.

Ruleset Processing

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.

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 (RewriteRule directives) and when a particular rule matches it optionally loops through existing corresponding conditions (RewriteCond 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.

Flow of RewriteRule and RewriteCond matching
Figure 1:The control flow through the rewriting ruleset

First the URL is matched against the Pattern of each rule. If it fails, mod_rewrite immediately stops processing this rule, and continues with the next rule. If the Pattern matches, mod_rewrite looks for corresponding rule conditions (RewriteCond directives, appearing immediately above the RewriteRule in the configuration). If none are present, it substitutes the URL with a new value, which is constructed from the string Substitution, 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 TestString by expanding variables, back-references, map lookups, etc. and then we try to match CondPattern 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 Substitution.


Apache SSL/TLS Şifrelemesi - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Apache SSL/TLS Şifrelemesi

Apache HTTP Sunucusunun mod_ssl modülü, Güvenli Soketler Katmanı (SSL) ve Aktarım Katmanı Güvenliği (TLS) protokollerinin kullanıldığı Sağlam Şifreleme desteğini sağlayan OpenSSL kütüphanesine bir arayüz içerir.

Belgeler

  • mod_ssl Yapılandırması Nasıl
  • SSL'ye Giriş
  • Uyumluluk
  • Sıkça Sorulan Sorular
  • Terimler

mod_ssl Modülü

Bu modülce sağlanan yönergeler ve ortam değişkenleri mod_ssl başvuru kılavuzunda ayrıntılı olarak açıklanmıştır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


SSL/TLS Strong Encryption: An Introduction - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > SSL/TLS

SSL/TLS Strong Encryption: An Introduction

As 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.

Cryptographic Techniques

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 [AC96]) and provide the basis for privacy, integrity, and authentication.

Cryptographic Algorithms

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 until it is decrypted. Once in this form, the message can only be decrypted by using 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.

There are two categories of cryptographic algorithms: conventional and public key.

Conventional cryptography
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. As long as this key is kept secret, nobody other than the sender or recipient can read the message. If Alice and the bank know a secret key, then they can send each other private messages. The task of sharing a key between sender and recipient before communicating, while also keeping it secret from others, can be problematic.
Public key cryptography
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).

Anyone can 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 can send private messages to the owner of a key-pair (the bank), by encrypting them using their public key. Only the bank will be able to decrypt them.

Message Digests

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 for her 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 the summaries are the same then the message has been received intact.

A summary such as this is called a message digest, one-way function or hash function. Message digests are used to create a short, fixed-length representation of a longer, variable-length message. Digest algorithms are designed to produce a unique digest for each message. Message digests are designed to make it impractically difficult to determine the message from the digest and (in theory) 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.

Another challenge that Alice faces is finding a way to send the digest to the bank securely; if the digest is not sent securely, its integrity may be compromised and with it the possibility for the bank to determine the integrity of the original message. Only if the digest is sent securely can the integrity of the associated message be determined.

One way to send the digest securely is to include it in a digital signature.

Digital Signatures

When Alice sends a message to the bank, the bank needs to ensure that the message is really from her, so an intruder cannot request a transaction involving her account. A digital signature, created by Alice and included with the message, serves this purpose.

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 can decrypt the signature using the public key, only the sender knows the private key. This means that only the sender can have signed the message. 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.

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).

Certificates

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 is part of the bank's key-pair, and not an intruder's. Similarly, the bank needs to verify that the message signature really was signed by the private key that belongs to Alice.

If each party has a certificate which validates the other's identity, confirms the public key and is signed by a trusted agency, then both can be assured that they are communicating with whom they think they are. Such a trusted agency is called a Certificate Authority and certificates are used for authentication.

Certificate Contents

A certificate associates a public key with the real identity of an individual, server, or other entity, known as the subject. As shown in Table 1, 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.

Table 1: Certificate Information

Subject | Distinguished Name, Public Key
Issuer | Distinguished Name, Signature
Period of Validity | Not Before Date, Not After Date
Administrative Information | Version, Serial Number
Extended Information | Basic Constraints, Netscape Flags, etc.

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 [X509], which defines the fields, field names and abbreviations used to refer to the fields (see Table 2).

Table 2: Distinguished Name Information

DN Field | Abbrev. | Description | Example
Common Name | CN | Name being certified | CN=Joe Average
Organization or Company | O | Name is associated with this organization | O=Snake Oil, Ltd.
Organizational Unit | OU | Name is associated with this organization unit, such as a department | OU=Research Institute
City/Locality | L | Name is located in this City | L=Snake City
State/Province | ST | Name is located in this State/Province | ST=Desert
Country | C | Name is located in this Country (ISO code) | C=XZ

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. For example, a Netscape browser requires that the Common Name for a certificate representing a server matches a wildcard pattern for the domain name of that server, such as *.snakeoil.com.

The binary format of a certificate is defined using the ASN.1 notation [ASN1] [PKCS]. 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 [MIME]. When placed between begin and end delimiter lines (as below), this encoded version is called a PEM ("Privacy Enhanced Mail") encoded certificate.

Example of a PEM-encoded certificate (snakeoil.crt)

-----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-----

Certificate Authorities

By verifying the information in a certificate request before granting the certificate, the Certificate Authority assures itself of 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 she is.

Certificate Chains

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.

Creating a Root-Level CA

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: who can vouch 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. Browsers are preconfigured to trust well-known certificate authorities, but it is important to 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.

A number of companies, such as Thawte and VeriSign have established themselves as Certificate Authorities. These companies provide the following services:

  • Verifying certificate requests
  • Processing certificate requests
  • Issuing and managing certificates

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.

Certificate Management

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 for how long certificates remain valid, they renew them and keep lists of certificates that were issued in the past but are no longer valid (Certificate Revocation Lists, or CRLs).

For example, if Alice is entitled to a certificate as an employee of a company but has now left that company, her certificate may need to be revoked. Because certificates are only issued after the subject's identity has been verified and can then be passed around to all those with whom the subject may communicate, it is impossible to tell from the certificate alone that it has been revoked. Therefore when examining certificates for validity it is necessary to contact the issuing Certificate Authority to check CRLs -- this is usually not an automated part of the process.

Note

If you use a Certificate Authority that browsers are not configured to trust 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.

Secure Sockets Layer (SSL)

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.

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 when establishing a protocol session.

Table 4: Versions of the SSL protocol

Version | Source | Description
SSL v2.0 | Vendor Standard (from Netscape Corp.) | First SSL protocol for which implementations exist
SSL v3.0 | Expired Internet Draft (from Netscape Corp.) [SSL3] | Revisions to prevent specific security attacks, add non-RSA ciphers and support for certificate chains
TLS v1.0 | Proposed Internet Standard (from IETF) [TLS1] | 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.
TLS v1.1 | Proposed Internet Standard (from IETF) [TLS11] | Update of TLS 1.0 to add protection against Cipher block chaining (CBC) attacks.
TLS v1.2 | Proposed Internet Standard (from IETF) [TLS12] | Update of TLS 1.2 deprecating MD5 as hash, and adding incompatibility to SSL so it will never negotiate the use of SSLv2.

There are a number of versions of the SSL protocol, as shown in Table 4. 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 [TLS] protocol standard, currently in development by the Internet Engineering Task Force (IETF).

Establishing a Session

The SSL session is established by following a handshake sequence between client and server, as shown in Figure 1. This sequence may vary, depending on whether the server is configured to provide a server certificate or request a client certificate. Although 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.

Note

Once an SSL session has been established, it may be reused. This avoids the performance penalty of repeating the many steps needed to start a session. To do this, the server assigns each SSL session a unique session identifier which is cached in the server and which the client can use in future connections to reduce the handshake time (until the session identifier expires from the cache of the server).

Figure 1: Simplified SSL Handshake Sequence

The elements of the handshake sequence, as used by the client and server, are listed below:

  1. Negotiate the Cipher Suite to be used during data transfer
  2. Establish and share a session key between client and server
  3. Optionally authenticate the server to the client
  4. Optionally authenticate the client to the server

The first step, Cipher Suite Negotiation, allows the client and server to choose a Cipher Suite supported by both of them. The SSL3.0 protocol specification defines 31 Cipher Suites. A Cipher Suite is defined by the following components:

  • Key Exchange Method
  • Cipher for Data Transfer
  • Message Digest for creating the Message Authentication Code (MAC)

These three elements are described in the sections that follow.

Key Exchange Method

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 RSA key exchange (when certificates are used), and Diffie-Hellman key exchange (for exchanging keys without certificates, or without prior communication between client and server).

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 protection against a man-in-the-middle-attack during the information exchange used to generating the shared key [AC96, p516].

Cipher for Data Transfer

SSL uses conventional symmetric cryptography, as described earlier, for encrypting messages in a session. There are nine choices of how to encrypt, including the option not to encrypt:

  • No encryption
  • Stream Ciphers
    • RC4 with 40-bit keys
    • RC4 with 128-bit keys
  • CBC Block Ciphers
    • RC2 with 40 bit key
    • DES with 40 bit key
    • DES with 56 bit key
    • Triple-DES with 168 bit key
    • Idea (128 bit key)
    • Fortezza (96 bit key)

"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 [AC96, ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" is currently one of the best and cryptographically strongest algorithms available, and "RC2" is a proprietary algorithm from RSA DSI [AC96, ch13].

Digest Function

The choice of digest function determines how a digest is created from a record unit. SSL supports the following:

  • No digest (Null choice)
  • MD5, a 128-bit hash
  • Secure Hash Algorithm (SHA-1), a 160-bit hash

The message digest is used to create a Message Authentication Code (MAC) which is encrypted with the message to verify integrity and to protect against replay attacks.

Handshake Sequence Protocol

The handshake sequence uses three protocols:

  • The SSL Handshake Protocol for performing the client and server SSL session establishment.
  • The SSL Change Cipher Spec Protocol for actually establishing agreement on the Cipher Suite for the session.
  • The SSL Alert Protocol for conveying SSL error messages between client and server.

These protocols, as well as application protocol data, are encapsulated in the SSL Record Protocol, as shown in Figure 2. 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.

Figure 2: SSL Protocol Stack

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 was no previous session, the Null cipher suite is used, which means there will be no encryption and messages will have no integrity digests, until the session has been established.

Data Transfer

The SSL Record Protocol, shown in Figure 3, is used to transfer application and SSL Control data between the client and server, where necessary 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, no major SSL implementations include support for compression).

Figure 3: SSL Record Protocol

Securing HTTP Communication

One common use of SSL is to secure Web HTTP communication between a browser and a webserver. This does not preclude the use of non-secured HTTP - the secure version (called HTTPS) is the same as plain HTTP over SSL, but uses the URL scheme https rather than http, and a different server port (by default, port 443). This functionality is a large part of what mod_ssl provides for the Apache webserver.

References

[AC96]
Bruce Schneier, Applied Cryptography, 2nd Edition, Wiley, 1996. See http://www.counterpane.com/ for various other materials by Bruce Schneier.
[ASN1]
ITU-T Recommendation X.208, Specification of Abstract Syntax Notation One (ASN.1), last updated 2008. See http://www.itu.int/ITU-T/asn1/.
[X509]
ITU-T Recommendation X.509, The Directory - Authentication Framework. For references, see http://en.wikipedia.org/wiki/X.509.
[PKCS]
Public Key Cryptography Standards (PKCS), RSA Laboratories Technical Notes, See http://www.rsasecurity.com/rsalabs/pkcs/.
[MIME]
N. Freed, N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, RFC2045. See for instance http://tools.ietf.org/html/rfc2045.
[SSL3]
Alan O. Freier, Philip Karlton, Paul C. Kocher, The SSL Protocol Version 3.0, 1996. See http://www.netscape.com/eng/ssl3/draft302.txt.
[TLS1]
Tim Dierks, Christopher Allen, The TLS Protocol Version 1.0, 1999. See http://ietf.org/rfc/rfc2246.txt.
[TLS11]
The TLS Protocol Version 1.1, 2006. See http://tools.ietf.org/html/rfc4346.
[TLS12]
The TLS Protocol Version 1.2, 2008. See http://tools.ietf.org/html/rfc5246.


SSL/TLS Strong Encryption: Compatibility - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > SSL/TLS

SSL/TLS Strong Encryption: Compatibility

This page covers backwards compatibility between mod_ssl and other SSL solutions. mod_ssl is not the only SSL solution for Apache; four additional products are (or were) also available: Ben Laurie's freely available Apache-SSL (from where mod_ssl were originally derived in 1998), Red Hat's commercial Secure Web Server (which was based on mod_ssl), Covalent's commercial Raven SSL Module (also based on mod_ssl) and finally C2Net's (now Red Hat's) commercial product Stronghold (based on a different evolution branch, named Sioux up to Stronghold 2.x, and based on mod_ssl since Stronghold 3.x).

mod_ssl mostly provides a superset of the functionality of all the other solutions, so it's simple to migrate from one of the older modules to mod_ssl. The configuration directives and environment variable names used by the older SSL solutions vary from those used in mod_ssl; mapping tables are included here to give the equivalents used by mod_ssl.

Configuration Directives

The mapping between configuration directives used by Apache-SSL 1.x and mod_ssl 2.0.x is given in Table 1. The mapping from Sioux 1.x and Stronghold 2.x is only partial because of special functionality in these interfaces which mod_ssl doesn't provide.

Table 1: Configuration Directive Mapping

Old Directive | mod_ssl Directive | Comment
Apache-SSL 1.x & mod_ssl 2.0.x compatibility:
SSLEnable | SSLEngine on | compactified
SSLDisable | SSLEngine off | compactified
SSLLogFile file |  | Use per-module LogLevel setting instead.
SSLRequiredCiphers spec | SSLCipherSuite spec | renamed
SSLRequireCipher c1 ... | SSLRequire %{SSL_CIPHER} in {"c1", ...} | generalized
SSLBanCipher c1 ... | SSLRequire not (%{SSL_CIPHER} in {"c1", ...}) | generalized
SSLFakeBasicAuth | SSLOptions +FakeBasicAuth | merged
SSLCacheServerPath dir | - | functionality removed
SSLCacheServerPort integer | - | functionality removed
Apache-SSL 1.x compatibility:
SSLExportClientCertificates | SSLOptions +ExportCertData | merged
SSLCacheServerRunDir dir | - | functionality not supported
Sioux 1.x compatibility:
SSL_CertFile file | SSLCertificateFile file | renamed
SSL_KeyFile file | SSLCertificateKeyFile file | renamed
SSL_CipherSuite arg | SSLCipherSuite arg | renamed
SSL_X509VerifyDir arg | SSLCACertificatePath arg | renamed
SSL_Log file | - | Use per-module LogLevel setting instead.
SSL_Connect flag | SSLEngine flag | renamed
SSL_ClientAuth arg | SSLVerifyClient arg | renamed
SSL_X509VerifyDepth arg | SSLVerifyDepth arg | renamed
SSL_FetchKeyPhraseFrom arg | - | not directly mappable; use SSLPassPhraseDialog
SSL_SessionDir dir | - | not directly mappable; use SSLSessionCache
SSL_Require expr | - | not directly mappable; use SSLRequire
SSL_CertFileType arg | - | functionality not supported
SSL_KeyFileType arg | - | functionality not supported
SSL_X509VerifyPolicy arg | - | functionality not supported
SSL_LogX509Attributes arg | - | functionality not supported
Stronghold 2.x compatibility:
StrongholdAccelerator engine | SSLCryptoDevice engine | renamed
StrongholdKey dir | - | functionality not needed
StrongholdLicenseFile dir | - | functionality not needed
SSLFlag flag | SSLEngine flag | renamed
SSLSessionLockFile file | SSLMutex file | renamed
SSLCipherList spec | SSLCipherSuite spec | renamed
RequireSSL | SSLRequireSSL | renamed
SSLErrorFile file | - | functionality not supported
SSLRoot dir | - | functionality not supported
SSL_CertificateLogDir dir | - | functionality not supported
AuthCertDir dir | - | functionality not supported
SSL_Group name | - | functionality not supported
SSLProxyMachineCertPath dir | SSLProxyMachineCertificatePath dir | renamed
SSLProxyMachineCertFile file | SSLProxyMachineCertificateFile file | renamed
SSLProxyCipherList spec | SSLProxyCipherSpec spec | renamed

Environment Variables

The mapping between environment variable names used by the older SSL solutions and the names used by mod_ssl is given in Table 2.

Table 2: Environment Variable Derivation

Old Variable | mod_ssl Variable | Comment
SSL_PROTOCOL_VERSION | SSL_PROTOCOL | renamed
SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
HTTPS_SECRETKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
HTTPS_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
HTTPS_CIPHER | SSL_CIPHER | renamed
HTTPS_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_SERVER_KEY_SIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SERVER_CERTIFICATE | SSL_SERVER_CERT | renamed
SSL_SERVER_CERT_START | SSL_SERVER_V_START | renamed
SSL_SERVER_CERT_END | SSL_SERVER_V_END | renamed
SSL_SERVER_CERT_SERIAL | SSL_SERVER_M_SERIAL | renamed
SSL_SERVER_SIGNATURE_ALGORITHM | SSL_SERVER_A_SIG | renamed
SSL_SERVER_DN | SSL_SERVER_S_DN | renamed
SSL_SERVER_CN | SSL_SERVER_S_DN_CN | renamed
SSL_SERVER_EMAIL | SSL_SERVER_S_DN_Email | renamed
SSL_SERVER_O | SSL_SERVER_S_DN_O | renamed
SSL_SERVER_OU | SSL_SERVER_S_DN_OU | renamed
SSL_SERVER_C | SSL_SERVER_S_DN_C | renamed
SSL_SERVER_SP | SSL_SERVER_S_DN_SP | renamed
SSL_SERVER_L | SSL_SERVER_S_DN_L | renamed
SSL_SERVER_IDN | SSL_SERVER_I_DN | renamed
SSL_SERVER_ICN | SSL_SERVER_I_DN_CN | renamed
SSL_SERVER_IEMAIL | SSL_SERVER_I_DN_Email | renamed
SSL_SERVER_IO | SSL_SERVER_I_DN_O | renamed
SSL_SERVER_IOU | SSL_SERVER_I_DN_OU | renamed
SSL_SERVER_IC | SSL_SERVER_I_DN_C | renamed
SSL_SERVER_ISP | SSL_SERVER_I_DN_SP | renamed
SSL_SERVER_IL | SSL_SERVER_I_DN_L | renamed
SSL_CLIENT_CERTIFICATE | SSL_CLIENT_CERT | renamed
SSL_CLIENT_CERT_START | SSL_CLIENT_V_START | renamed
SSL_CLIENT_CERT_END | SSL_CLIENT_V_END | renamed
SSL_CLIENT_CERT_SERIAL | SSL_CLIENT_M_SERIAL | renamed
SSL_CLIENT_SIGNATURE_ALGORITHM | SSL_CLIENT_A_SIG | renamed
SSL_CLIENT_DN | SSL_CLIENT_S_DN | renamed
SSL_CLIENT_CN | SSL_CLIENT_S_DN_CN | renamed
SSL_CLIENT_EMAIL | SSL_CLIENT_S_DN_Email | renamed
SSL_CLIENT_O | SSL_CLIENT_S_DN_O | renamed
SSL_CLIENT_OU | SSL_CLIENT_S_DN_OU | renamed
SSL_CLIENT_C | SSL_CLIENT_S_DN_C | renamed
SSL_CLIENT_SP | SSL_CLIENT_S_DN_SP | renamed
SSL_CLIENT_L | SSL_CLIENT_S_DN_L | renamed
SSL_CLIENT_IDN | SSL_CLIENT_I_DN | renamed
SSL_CLIENT_ICN | SSL_CLIENT_I_DN_CN | renamed
SSL_CLIENT_IEMAIL | SSL_CLIENT_I_DN_Email | renamed
SSL_CLIENT_IO | SSL_CLIENT_I_DN_O | renamed
SSL_CLIENT_IOU | SSL_CLIENT_I_DN_OU | renamed
SSL_CLIENT_IC | SSL_CLIENT_I_DN_C | renamed
SSL_CLIENT_ISP | SSL_CLIENT_I_DN_SP | renamed
SSL_CLIENT_IL | SSL_CLIENT_I_DN_L | renamed
SSL_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SECKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
SSL_SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
SSL_STRONG_CRYPTO | - | Not supported by mod_ssl
SSL_SERVER_KEY_EXP | - | Not supported by mod_ssl
SSL_SERVER_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_SERVER_KEY_SIZE | - | Not supported by mod_ssl
SSL_SERVER_SESSIONDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTIFICATELOGDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILETYPE | - | Not supported by mod_ssl
SSL_CLIENT_KEY_EXP | - | Not supported by mod_ssl
SSL_CLIENT_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_CLIENT_KEY_SIZE | - | Not supported by mod_ssl

Custom Log Functions

When mod_ssl is enabled, additional functions exist for the Custom Log Format of mod_log_config as documented in the Reference Chapter. Beside the ``%{varname}x'' eXtension format function which can be used to expand any variables provided by any module, an additional Cryptography ``%{name}c'' cryptography format function exists for backward compatibility. The currently implemented function calls are listed in Table 3.

Table 3: Custom Log Cryptography Function

Function Call | Description
%...{version}c | SSL protocol version
%...{cipher}c | SSL cipher
%...{subjectdn}c | Client Certificate Subject Distinguished Name
%...{issuerdn}c | Client Certificate Issuer Distinguished Name
%...{errcode}c | Certificate Verification Error (numerical)
%...{errstr}c | Certificate Verification Error (string)


SSL/TLS Strong Encryption: How-To - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > SSL/TLS

SSL/TLS Strong Encryption: How-To

This document is intended to get you started, and get a few things working. You are strongly encouraged to read the rest of the SSL documentation, and arrive at a deeper understanding of the material, before progressing to the advanced techniques.

Basic Configuration Example

Your SSL configuration will need to contain, at minimum, the following directives.

LoadModule ssl_module modules/mod_ssl.so

Listen 443
<VirtualHost *:443>
    ServerName www.example.com
    SSLEngine on
    SSLCertificateFile "/path/to/www.example.com.cert"
    SSLCertificateKeyFile "/path/to/www.example.com.key"
</VirtualHost>

Cipher Suites and Enforcing Strong Security

  • How can I create an SSL server which accepts strong encryption only?
  • How can I create an SSL server which accepts all types of ciphers in general, but requires a strong cipher for access to a particular URL?

How can I create an SSL server which accepts strong encryption only?

The following enables only the strongest ciphers:

SSLCipherSuite HIGH:!aNULL:!MD5

While with the following configuration you specify a preference for specific speed-optimized ciphers (which will be selected by mod_ssl, provided that they are supported by the client):

SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
SSLHonorCipherOrder on

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?

Obviously, a server-wide SSLCipherSuite which restricts ciphers to the strong variants, isn't the answer here. However, mod_ssl can be reconfigured within Location blocks, to give a per-directory solution, and can automatically force a renegotiation of the SSL parameters to meet the new configuration. This can be done as follows:

# be liberal in general
SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL

<Location "/strong/area">
# but https://hostname/strong/area/ and below
# requires strong ciphers
SSLCipherSuite HIGH:!aNULL:!MD5
</Location>

OCSP Stapling

The Online Certificate Status Protocol (OCSP) is a mechanism for determining whether or not a server certificate has been revoked, and OCSP Stapling is a special form of this in which the server, such as httpd and mod_ssl, maintains current OCSP responses for its certificates and sends them to clients which communicate with the server. Most certificates contain the address of an OCSP responder maintained by the issuing Certificate Authority, and mod_ssl can communicate with that responder to obtain a signed response that can be sent to clients communicating with the server.

Because the client can obtain the certificate revocation status from the server, without requiring an extra connection from the client to the Certificate Authority, OCSP Stapling is the preferred way for the revocation status to be obtained. Other benefits of eliminating the communication between clients and the Certificate Authority are that the client browsing history is not exposed to the Certificate Authority and obtaining status is more reliable by not depending on potentially heavily loaded Certificate Authority servers.

Because the response obtained by the server can be reused for all clients using the same certificate during the time that the response is valid, the overhead for the server is minimal.

Once general SSL support has been configured properly, enabling OCSP Stapling generally requires only very minor modifications to the httpd configuration — the addition of these two directives:

SSLUseStapling On
SSLStaplingCache "shmcb:logs/ssl_stapling(32768)"

These directives are placed at global scope (i.e., not within a virtual host definition) wherever other global SSL configuration directives are placed, such as in conf/extra/httpd-ssl.conf for normal open source builds of httpd, /etc/apache2/mods-enabled/ssl.conf for the Ubuntu or Debian-bundled httpd, etc.

The path on the SSLStaplingCache directive (e.g., logs/) should match the one on the SSLSessionCache directive. This path is relative to ServerRoot.

This particular SSLStaplingCache directive requires mod_socache_shmcb (from the shmcb prefix on the directive's argument). This module is usually enabled already for SSLSessionCache or on behalf of some module other than mod_ssl. If you enabled an SSL session cache using a mechanism other than mod_socache_shmcb, use that alternative mechanism for SSLStaplingCache as well. For example:

SSLSessionCache "dbm:logs/ssl_scache"
SSLStaplingCache "dbm:logs/ssl_stapling"

You can use the openssl command-line program to verify that an OCSP response is sent by your server:

$ openssl s_client -connect www.example.com:443 -status -servername www.example.com
...
OCSP response:
======================================
OCSP Response Data:
    OCSP Response Status: successful (0x0)
    Response Type: Basic OCSP Response
...
    Cert Status: Good
...

The following sections highlight the most common situations which require further modification to the configuration. Refer also to the mod_ssl reference manual.

If more than a few SSL certificates are used for the server

OCSP responses are stored in the SSL stapling cache. While the responses are typically a few hundred to a few thousand bytes in size, mod_ssl supports OCSP responses up to around 10K bytes in size. With more than a few certificates, the stapling cache size (32768 bytes in the example above) may need to be increased. Error message AH01929 will be logged in case of an error storing a response.

If the certificate does not point to an OCSP responder, or if a different address must be used

Refer to the SSLStaplingForceURL directive.

You can confirm that a server certificate points to an OCSP responder using the openssl command-line program, as follows:

$ openssl x509 -in ./www.example.com.crt -text | grep 'OCSP.*http'
OCSP - URI:http://ocsp.example.com

If the OCSP URI is provided and the web server can communicate to it directly without using a proxy, no configuration is required. Note that firewall rules that control outbound connections from the web server may need to be adjusted.

If no OCSP URI is provided, contact your Certificate Authority to determine if one is available; if so, configure it with SSLStaplingForceURL in the virtual host that uses the certificate.

If multiple SSL-enabled virtual hosts are configured and OCSP Stapling should be disabled for some

Add SSLUseStapling Off to the virtual hosts for which OCSP Stapling should be disabled.

If the OCSP responder is slow or unreliable

Several directives are available to handle timeouts and errors. Refer to the documentation for the SSLStaplingFakeTryLater, SSLStaplingResponderTimeout, and SSLStaplingReturnResponderErrors directives.

If mod_ssl logs error AH02217

AH02217: ssl_stapling_init_cert: Can't retrieve issuer certificate!

In order to support OCSP Stapling when a particular server certificate is used, the certificate chain for that certificate must be configured. If it was not configured as part of enabling SSL, the AH02217 error will be issued when stapling is enabled, and an OCSP response will not be provided for clients using the certificate.

Refer to the SSLCertificateChainFile and SSLCertificateFile for instructions for configuring the certificate chain.

Client Authentication and Access Control

  • How can I force clients to authenticate using certificates?
  • How can I force clients to authenticate using certificates for a particular URL, but still allow arbitrary clients to access the rest of the server?
  • How can I allow only clients who have certificates to access a particular URL, but allow all clients to access the rest of the server?
  • How can I require HTTPS with strong ciphers, and either basic authentication or client certificates, for access to part of the Intranet website, for clients coming from the Internet?

How can I force clients to authenticate using certificates?

When you know all of your users (eg, as is often the case on a corporate Intranet), you can require plain certificate authentication. All you need to do is to create client certificates signed by your own CA certificate (ca.crt) and then verify the clients against this certificate.

# 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"

How can I force clients to authenticate using certificates for a particular URL, but still allow arbitrary clients to access the rest of the server?

To force clients to authenticate using certificates for a particular URL, you can use the per-directory reconfiguration features of mod_ssl:

SSLVerifyClient none
SSLCACertificateFile "conf/ssl.crt/ca.crt"

<Location "/secure/area">
SSLVerifyClient require
SSLVerifyDepth 1
</Location>

How can I allow only clients who have certificates to access a particular URL, but allow all clients to access the rest of the server?

The key to doing this is checking that part of the client certificate matches what you expect. Usually this means checking all or part of the Distinguished Name (DN), to see if it contains some known string. There are two ways to do this, using either mod_auth_basic or SSLRequire.

The mod_auth_basic method is generally required when the certificates are completely arbitrary, or when their DNs have no common fields (usually the organisation, etc.). In this case, you should establish a password database containing all clients allowed, as follows:

SSLVerifyClient      none
SSLCACertificateFile "conf/ssl.crt/ca.crt"
SSLCACertificatePath "conf/ssl.crt"

<Directory "/usr/local/apache2/htdocs/secure/area">
    SSLVerifyClient      require
    SSLVerifyDepth       5
    SSLOptions           +FakeBasicAuth
    SSLRequireSSL
    AuthName             "Snake Oil Authentication"
    AuthType             Basic
    AuthBasicProvider    file
    AuthUserFile         "/usr/local/apache2/conf/httpd.passwd"
    Require              valid-user
</Directory>

The password used in this example is the DES encrypted string "password". See the SSLOptions docs for more information.

httpd.passwd

/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

When your clients are all part of a common hierarchy, which is encoded into the DN, you can match them more easily using SSLRequire, as follows:

SSLVerifyClient      none
SSLCACertificateFile "conf/ssl.crt/ca.crt"
SSLCACertificatePath "conf/ssl.crt"

<Directory "/usr/local/apache2/htdocs/secure/area">
  SSLVerifyClient      require
  SSLVerifyDepth       5
  SSLOptions           +FakeBasicAuth
  SSLRequireSSL
  SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
               and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
</Directory>

How can I require HTTPS with strong ciphers, and either basic authentication or client certificates, for access to part of the Intranet website, for clients coming from the Internet? I still want to allow plain HTTP access for clients on the Intranet.

These examples presume that clients on the Intranet have IPs in the range 192.168.1.0/24, and that the part of the Intranet website you want to allow internet access to is /usr/local/apache2/htdocs/subarea. This configuration should remain outside of your HTTPS virtual host, so that it applies to both HTTPS and HTTP.

SSLCACertificateFile "conf/ssl.crt/company-ca.crt"

<Directory "/usr/local/apache2/htdocs">
    #   Outside the subarea only Intranet access is granted
    Require              ip 192.168.1.0/24
</Directory>

<Directory "/usr/local/apache2/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
    Require              ip 192.168.1.0/24

    #   HTTP Basic Authentication
    AuthType             basic
    AuthName             "Protected Intranet Area"
    AuthBasicProvider    file
    AuthUserFile         "conf/protected.passwd"
    Require              valid-user
</Directory>

Logging

mod_ssl can log extremely verbose debugging information to the error log, when its LogLevel is set to the higher trace levels. On the other hand, on a very busy server, level info may already be too much. Remember that you can configure the LogLevel per module to suite your needs.


SSL/TLS Strong Encryption: FAQ - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > SSL/TLS

SSL/TLS Strong Encryption: FAQ

The wise man doesn't give the right answers, he poses the right questions.

-- Claude Levi-Strauss

Installation

  • Why do I get permission errors related to SSLMutex when I start Apache?
  • Why does mod_ssl stop with the error "Failed to generate temporary 512 bit RSA private key" when I start Apache?

Why do I get permission errors related to SSLMutex when I start Apache?

Errors such as ``mod_ssl: Child could not open SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) [...] System: Permission denied (errno: 13)'' are usually caused by overly restrictive permissions on the parent directories. Make sure that all parent directories (here /opt, /opt/apache and /opt/apache/logs) have the x-bit set for, at minimum, the UID under which Apache's children are running (see the User directive).

Why does mod_ssl stop with the error "Failed to generate temporary 512 bit RSA private key" when I start Apache?

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 /dev/random). 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.

To prevent this error, mod_ssl has to provide enough entropy to the PRNG to allow it to work correctly. This can be done via the SSLRandomSeed directive.

Configuration

  • Is it possible to provide HTTP and HTTPS from the same server?
  • Which port does HTTPS use?
  • How do I speak HTTPS manually for testing purposes?
  • Why does the connection hang when I connect to my SSL-aware Apache server?
  • Why do I get ``Connection Refused'' errors, when trying to access my newly installed Apache+mod_ssl server via HTTPS?
  • Why are the SSL_XXX variables not available to my CGI & SSI scripts?
  • How can I switch between HTTP and HTTPS in relative hyperlinks?

Is it possible to provide HTTP and HTTPS from the same server?

Yes. HTTP and HTTPS use different server ports (HTTP binds to port 80, HTTPS to port 443), so there is no direct conflict between them. You can either run two separate server instances bound to these ports, or use Apache's elegant virtual hosting facility to create two virtual servers, both served by the same instance of Apache - one responding over HTTP to requests on port 80, and the other responding over HTTPS to requests on port 443.

Which port does HTTPS use?

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. For example, if your server is set up to serve pages over HTTPS on port 8080, you can access them at https://example.com:8080/

How do I speak HTTPS manually for testing purposes?

While you usually just use

$ telnet localhost 80
GET / HTTP/1.0

for simple testing of Apache via HTTP, it's not so easy for HTTPS because of the SSL protocol between TCP and HTTP. With the help of OpenSSL's s_client command, however, you can do a similar check via HTTPS:

$ openssl s_client -connect localhost:443 -state -debug
GET / HTTP/1.0

Before the actual HTTP response you will receive detailed information about the SSL handshake. For a more general command line client which directly understands both HTTP and HTTPS, can perform GET and POST operations, can use a proxy, supports byte ranges, etc. you should have a look at the nifty cURL tool. Using this, you can check that Apache is responding correctly to requests via HTTP and HTTPS as follows:

$ curl http://localhost/
$ curl https://localhost/

Why does the connection hang when I connect to my SSL-aware Apache server?

This can happen when you try to connect to a HTTPS server (or virtual server) via HTTP (eg, using http://example.com/ instead of https://example.com). It can also happen when trying to connect via HTTPS to a HTTP server (eg, using https://example.com/ on a server which doesn't support HTTPS, or which supports it on a non-standard port). Make sure that you're connecting to a (virtual) server that supports SSL.

Why do I get ``Connection Refused'' messages, when trying to access my newly installed Apache+mod_ssl server via HTTPS?

This error can be caused by an incorrect configuration. Please make sure that your Listen directives match your <VirtualHost> directives. If all else fails, please start afresh, using the default configuration provided by mod_ssl.

Why are the SSL_XXX variables not available to my CGI & SSI scripts?

Please make sure you have ``SSLOptions +StdEnvVars'' enabled for the context of your CGI/SSI requests.

How can I switch between HTTP and HTTPS in relative hyperlinks?

Usually, to switch between HTTP and HTTPS, you have to use fully-qualified hyperlinks (because you have to change the URL scheme). Using mod_rewrite however, you can manipulate relative hyperlinks, to achieve the same effect.

RewriteEngine on
RewriteRule   "^/(.*)_SSL$"   "https://%{SERVER_NAME}/$1" [R,L]
RewriteRule   "^/(.*)_NOSSL$" "http://%{SERVER_NAME}/$1"  [R,L]

This rewrite ruleset lets you use hyperlinks of the form <a href="document.html_SSL">, to switch to HTTPS in a relative link. (Replace SSL with NOSSL to switch to HTTP.)

Certificates

  • What are RSA Private Keys, CSRs and Certificates?
  • Is there a difference on startup between a non-SSL-aware Apache and an SSL-aware Apache?
  • How do I create a self-signed SSL Certificate for testing purposes?
  • How do I create a real SSL Certificate?
  • How do I create and use my own Certificate Authority (CA)?
  • How can I change the pass-phrase on my private key file?
  • How can I get rid of the pass-phrase dialog at Apache startup time?
  • How do I verify that a private key matches its Certificate?
  • How can I convert a certificate from PEM to DER format?
  • Why do browsers complain that they cannot verify my server certificate?

What are RSA Private Keys, CSRs and Certificates?

An 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), who will convert it into a real Certificate, by signing it.

A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by the 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 Introduction chapter for a general description of the SSL protocol.

Is there a difference on startup between a non-SSL-aware Apache and an SSL-aware Apache?

Yes. In general, starting Apache with mod_ssl built-in is just like starting Apache without it. However, if you have a passphrase on your SSL private key file, a startup dialog will pop up which asks you to enter the pass phrase.

Having to manually enter the passphrase when starting the server can be problematic - for example, when starting the server from the system boot scripts. In this case, you can follow the steps below to remove the passphrase from your private key. Bear in mind that doing so brings additional security risks - proceed with caution!

How do I create a self-signed SSL Certificate for testing purposes?

  1. Make sure OpenSSL is installed and in your PATH.

  2. Run the following command, to create server.key and server.crt files:
    $ openssl req -new -x509 -nodes -out server.crt -keyout server.key
    These can be used as follows in your httpd.conf file:
    SSLCertificateFile    "/path/to/this/server.crt"
SSLCertificateKeyFile "/path/to/this/server.key"
  3. It is important that you are aware that this server.key does not have any passphrase. To add a passphrase to the key, you should run the following command, and enter & verify the passphrase as requested.

    $ openssl rsa -des3 -in server.key -out server.key.new
    $ mv server.key.new server.key

    Please backup the server.key file, and the passphrase you entered, in a secure location.

How do I create a real SSL Certificate?

Here is a step-by-step description:

  1. Make sure OpenSSL is installed and in your PATH.

  2. Create a RSA private key for your Apache server (will be Triple-DES encrypted and PEM formatted):

    $ openssl genrsa -des3 -out server.key 2048

    Please backup this server.key file and the pass-phrase you entered in a secure location. You can see the details of this RSA private key by using the command:

    $ openssl rsa -noout -text -in server.key

    If necessary, you can also create a decrypted PEM version (not recommended) of this RSA private key with:

    $ openssl rsa -in server.key -out server.key.unsecure

  3. Create a Certificate Signing Request (CSR) with the server RSA private key (output will be PEM formatted):

    $ openssl req -new -key server.key -out server.csr

    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 https://www.foo.dom/, enter "www.foo.dom" here. You can see the details of this CSR by using

    $ openssl req -noout -text -in server.csr

  4. You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) to be signed. Once the CSR has been signed, you will have a real Certificate, which can be used by Apache. You can have a CSR signed by a commercial CA, or you can create your own CA to sign it.
    Commercial CAs usually ask you to post the CSR into a web form, pay for the signing, and then send a signed Certificate, which you can store in a server.crt file.
    For details on how to create your own CA, and use this to sign a CSR, see below.
    Once your CSR has been signed, you can see the details of the Certificate as follows:

    $ openssl x509 -noout -text -in server.crt
  5. You should now have two files: server.key and server.crt. These can be used as follows in your httpd.conf file:
    SSLCertificateFile    "/path/to/this/server.crt"
SSLCertificateKeyFile "/path/to/this/server.key"
    The server.csr file is no longer needed.

How do I create and use my own Certificate Authority (CA)?

The short answer is to use the CA.sh or CA.pl script provided by OpenSSL. Unless you have a good reason not to, you should use these for preference. If you cannot, you can create a self-signed certificate as follows:

  1. Create a RSA private key for your server (will be Triple-DES encrypted and PEM formatted):

    $ openssl genrsa -des3 -out server.key 2048

    Please backup this server.key file and the pass-phrase you entered in a secure location. You can see the details of this RSA private key by using the command:

    $ openssl rsa -noout -text -in server.key

    If necessary, you can also create a decrypted PEM version (not recommended) of this RSA private key with:

    $ openssl rsa -in server.key -out server.key.unsecure

  2. Create a self-signed certificate (X509 structure) with the RSA key you just created (output will be PEM formatted):

    $ openssl req -new -x509 -nodes -sha1 -days 365 -key server.key -out server.crt -extensions usr_cert

    This signs the server CSR and results in a server.crt file.
    You can see the details of this Certificate using:

    $ openssl x509 -noout -text -in server.crt

How can I change the pass-phrase on my private key file?

You simply have to read it with the old pass-phrase and write it again, specifying the new pass-phrase. You can accomplish this with the following commands:

$ openssl rsa -des3 -in server.key -out server.key.new
$ mv server.key.new server.key

The first time you're asked for a PEM pass-phrase, you should enter the old pass-phrase. After that, you'll be asked again to enter a pass-phrase - this time, use the new pass-phrase. If you are asked to verify the pass-phrase, you'll need to enter the new pass-phrase a second time.

How can I get rid of the pass-phrase dialog at Apache startup time?

The reason 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 decrypt this file, so it can be read and parsed. Removing the pass-phrase removes a layer of security from your server - proceed with caution!

  1. Remove the encryption from the RSA private key (while keeping a backup copy of the original file):

    $ cp server.key server.key.org
    $ openssl rsa -in server.key.org -out server.key

  2. Make sure the server.key file is only readable by root:

    $ chmod 400 server.key

Now server.key contains 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 this file are 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 user, and have the key readable only by root).

As an alternative approach you can use the ``SSLPassPhraseDialog exec:/path/to/program'' facility. Bear in mind that this is neither more nor less secure, of course.

How do I verify that a private key matches its Certificate?

A private key contains a series of numbers. Two of these numbers form the "public key", the others are part of the "private key". The "public key" bits are included when you generate a CSR, and subsequently form part of the associated Certificate.

To check that the public key in your Certificate matches the public portion of your private key, you simply need to compare these numbers. To view the Certificate and the key run the commands:

$ openssl x509 -noout -text -in server.crt
$ openssl rsa -noout -text -in server.key

The `modulus' and the `public exponent' portions in the key and the Certificate must match. As the public exponent is usually 65537 and it's difficult to visually check that the long modulus numbers are the same, you can use the following approach:

$ openssl x509 -noout -modulus -in server.crt | openssl md5
$ openssl rsa -noout -modulus -in server.key | openssl md5

This leaves you with two rather shorter numbers to compare. It is, in theory, possible that these numbers may be the same, without the modulus numbers being the same, but the chances of this are overwhelmingly remote.

Should you wish to check to which key or certificate a particular CSR belongs you can perform the same calculation on the CSR as follows:

$ openssl req -noout -modulus -in server.csr | openssl md5

How can I convert a certificate from PEM to DER format?

The default certificate format for OpenSSL is PEM, which is simply 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 cert.pem into the corresponding DER file cert.der using the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER

Why do browsers complain that they cannot verify my server certificate?

One reason this might happen is because your server certificate is signed by an intermediate CA. Various CAs, such as Verisign or Thawte, have started signing certificates not with their root certificate but with intermediate certificates.

Intermediate CA certificates lie between the root CA certificate (which is installed in the browsers) and the server certificate (which you installed on the server). In order for the browser to be able to traverse and verify the trust chain from the server certificate to the root certificate it needs need to be given the intermediate certificates. The CAs should be able to provide you such intermediate certificate packages that can be installed on the server.

You need to include those intermediate certificates with the SSLCertificateChainFile directive.

The SSL Protocol

  • Why do I get lots of random SSL protocol errors under heavy server load?
  • Why does my webserver have a higher load, now that it serves SSL encrypted traffic?
  • Why do HTTPS connections to my server sometimes take up to 30 seconds to establish a connection?
  • What SSL Ciphers are supported by mod_ssl?
  • Why do I get ``no shared cipher'' errors, when trying to use Anonymous Diffie-Hellman (ADH) ciphers?
  • Why do I get a 'no shared ciphers' error when connecting to my newly installed server?
  • Why can't I use SSL with name-based/non-IP-based virtual hosts?
  • Is it possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?
  • How do I get SSL compression working?
  • When I use Basic Authentication over HTTPS the lock icon in Netscape browsers stays unlocked when the dialog pops up. Does this mean the username/password is being sent unencrypted?
  • Why do I get I/O errors when connecting via HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?
  • How do I enable TLS-SRP?
  • Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?

Why do I get lots of random SSL protocol errors under heavy server load?

There can be a number of reasons for this, but the main one is problems with the SSL session Cache specified by the SSLSessionCache directive. The DBM session cache is the most likely source of the problem, so using the SHM session cache (or no cache at all) may help.

Why does my webserver have a higher load, now that it serves SSL encrypted traffic?

SSL uses strong cryptographic encryption, which necessitates a lot of number crunching. When you request a webpage via HTTPS, everything (even the images) is encrypted before it is transferred. So increased HTTPS traffic leads to load increases.

Why do HTTPS connections to my server sometimes take up to 30 seconds to establish a connection?

This is usually caused by a /dev/random device for SSLRandomSeed which blocks the read(2) call until enough entropy is available to service the request. More information is available in the reference manual for the SSLRandomSeed directive.

What SSL Ciphers are supported by mod_ssl?

Usually, any SSL ciphers supported by the version of OpenSSL in use, are also supported by mod_ssl. Which ciphers are available can depend on the way you built OpenSSL. Typically, at least the following ciphers are supported:

  1. RC4 with SHA1
  2. AES with SHA1
  3. Triple-DES with SHA1

To determine the actual list of ciphers available, you should run the following:

$ openssl ciphers -v

Why do I get ``no shared cipher'' errors, when trying to use Anonymous Diffie-Hellman (ADH) ciphers?

By default, OpenSSL does not allow ADH ciphers, for security reasons. Please be sure you are aware of the potential side-effects if you choose to enable these ciphers.

In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must build OpenSSL with ``-DSSL_ALLOW_ADH'', and then add ``ADH'' into your SSLCipherSuite.

Why do I get a 'no shared ciphers' error when connecting to my newly installed server?

Either you have made a mistake with your SSLCipherSuite directive (compare it with the pre-configured example in extra/httpd-ssl.conf) or you chose to use DSA/DH algorithms instead of RSA when you generated your private key and ignored or overlooked the warnings. If you have chosen DSA/DH, then your server cannot communicate using RSA-based SSL ciphers (at least until you configure an additional RSA-based certificate/key pair). Modern browsers like NS or IE can only communicate over SSL using RSA ciphers. The result is the "no shared ciphers" error. To fix this, regenerate your server certificate/key pair, using the RSA algorithm.

Why can't I use SSL with name-based/non-IP-based virtual hosts?

The reason is very technical, and a somewhat "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 go to the correct virtual server Apache has to know the Host HTTP header field. To do this, the HTTP request header has to be read. This cannot be done before the SSL handshake is finished, but the information is needed in order to complete the SSL handshake phase. See the next question for how to circumvent this issue.

Note that if you have a wildcard SSL certificate, or a certificate that has multiple hostnames on it using subjectAltName fields, you can use SSL on name-based virtual hosts without further workarounds.

Is it possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?

Name-Based Virtual Hosting is a very popular method of identifying different virtual hosts. It allows you to use the same IP address and the same port number for many different sites. When people move on to SSL, it seems natural to assume that the same method can be used to have lots of different SSL virtual hosts on the same server.

It is possible, but only if using a 2.2.12 or later web server, built with 0.9.8j or later OpenSSL. This is because it requires a feature that only the most recent revisions of the SSL specification added, called Server Name Indication (SNI).

Note that if you have a wildcard SSL certificate, or a certificate that has multiple hostnames on it using subjectAltName fields, you can use SSL on name-based virtual hosts without further workarounds.

The reason is that the SSL protocol is a separate layer which encapsulates the HTTP protocol. So the SSL session is a separate transaction, that takes place before the HTTP session has begun. The server receives an SSL request on IP address X and port Y (usually 443). Since the SSL request did not contain any Host: field, the server had no way to decide which SSL virtual host to use. Usually, it just used the first one it found which matched the port and IP address specified.

If you are using a version of the web server and OpenSSL that support SNI, though, and the client's browser also supports SNI, then the hostname is included in the original SSL request, and the web server can select the correct SSL virtual host.

You can, of course, use Name-Based Virtual Hosting to identify many non-SSL virtual hosts (all on port 80, for example) and then have a single SSL virtual host (on port 443). But if you do this, you must make sure to put the non-SSL port number on the NameVirtualHost directive, e.g.

NameVirtualHost 192.168.1.1:80

Other workaround solutions include:

Using separate IP addresses for different SSL hosts. Using different port numbers for different SSL hosts.

How do I get SSL compression working?

Although SSL compression negotiation was defined in the specification of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as a negotiable standard compression method.

OpenSSL 0.9.8 started to support this by default when compiled with the zlib option. If both the client and the server support compression, it will be used. However, most clients still try to initially connect with an SSLv2 Hello. As SSLv2 did not include an array of preferred compression algorithms in its handshake, compression cannot be negotiated with these clients. If the client disables support for SSLv2, either an SSLv3 or TLS Hello may be sent, depending on which SSL library is used, and compression may be set up. You can verify whether clients make use of SSL compression by logging the %{SSL_COMPRESS_METHOD}x variable.

When I use Basic Authentication over HTTPS the lock icon in Netscape browsers stays unlocked when the dialog pops up. Does this mean the username/password is being sent unencrypted?

No, the username/password is transmitted encrypted. The icon in Netscape browsers is not actually synchronized with the SSL/TLS layer. It only toggles to the locked state when the first part of the actual webpage data is transferred, which may confuse people. The Basic Authentication facility is part of the HTTP layer, which is above the SSL/TLS layer in HTTPS. Before any HTTP data communication takes place in HTTPS, the SSL/TLS layer has already completed its handshake phase, and switched to encrypted communication. So don't be confused by this icon.

Why do I get I/O errors when connecting via HTTPS to an Apache+mod_ssl server with older versions of Microsoft Internet Explorer (MSIE)?

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 in some MSIE versions. You can work around these problems by forcing Apache not to use HTTP/1.1, keep-alive connections or send the SSL close notify messages to MSIE clients. This can be done by using the following directive in your SSL-aware virtual host section:

SetEnvIf User-Agent "MSIE [2-5]" \
         nokeepalive ssl-unclean-shutdown \
         downgrade-1.0 force-response-1.0

Further, some MSIE versions have problems with particular ciphers. Unfortunately, it is not possible to implement a MSIE-specific workaround for this, because the ciphers are needed as early as the SSL handshake phase. So a MSIE-specific SetEnvIf won't solve these problems. Instead, you will have to make more drastic adjustments to the global parameters. Before you decide to do this, make sure your clients really have problems. If not, do not make these changes - they will affect all your clients, MSIE or otherwise.

How do I enable TLS-SRP?

TLS-SRP (Secure Remote Password key exchange for TLS, specified in RFC 5054) can supplement or replace certificates in authenticating an SSL connection. To use TLS-SRP, set the SSLSRPVerifierFile directive to point to an OpenSSL SRP verifier file. To create the verifier file, use the openssl tool:

openssl srp -srpvfile passwd.srpv -add username

After creating this file, specify it in the SSL server configuration:

SSLSRPVerifierFile /path/to/passwd.srpv

To force clients to use non-certificate TLS-SRP cipher suites, use the following directive:

SSLCipherSuite "!DSS:!aRSA:SRP"

Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?

Beginning with version 2.4.7, mod_ssl will use DH parameters which include primes with lengths of more than 1024 bits. Java 7 and earlier limit their support for DH prime sizes to a maximum of 1024 bits, however.

If your Java-based client aborts with exceptions such as java.lang.RuntimeException: Could not generate DH keypair and java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64, and can only range from 512 to 1024 (inclusive), and httpd logs tlsv1 alert internal error (SSL alert number 80) (at LogLevel info or higher), you can either rearrange mod_ssl's cipher list with SSLCipherSuite (possibly in conjunction with SSLHonorCipherOrder), or you can use custom DH parameters with a 1024-bit prime, which will always have precedence over any of the built-in DH parameters.

To generate custom DH parameters, use the openssl dhparam 1024 command. Alternatively, you can use the following standard 1024-bit DH parameters from RFC 2409, section 6.2:

-----BEGIN DH PARAMETERS-----
MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
-----END DH PARAMETERS-----

Add the custom parameters including the "BEGIN DH PARAMETERS" and "END DH PARAMETERS" lines to the end of the first certificate file you have configured using the SSLCertificateFile directive.

mod_ssl Support

  • What information resources are available in case of mod_ssl problems?
  • What support contacts are available in case of mod_ssl problems?
  • What information should I provide when writing a bug report?
  • I had a core dump, can you help me?
  • How do I get a backtrace, to help find the reason for my core dump?

What information resources are available in case of mod_ssl problems?

The following information resources are available. In case of problems you should search here first.

Answers in the User Manual's F.A.Q. List (this)
http://httpd.apache.org/docs/2.4/ssl/ssl_faq.html
First check the F.A.Q. (this text). If your problem is a common one, it may have been answered several times before, and been included in this doc.

What support contacts are available in case of mod_ssl problems?

The following lists all support possibilities for mod_ssl, in order of preference. Please go through these possibilities in this order - don't just pick the one you like the look of.

  1. Send a Problem Report to the Apache httpd Users Support Mailing List
    users@httpd.apache.org
    This is the second way of submitting your problem report. Again, you must subscribe to the list first, but you can then easily discuss your problem with the whole Apache httpd user community.
  2. Write a Problem Report in the Bug Database
    http://httpd.apache.org/bug_report.html
    This is the last way of submitting your problem report. You should only do this if you've already posted to the mailing lists, and had no success. Please follow the instructions on the above page carefully.

What information should I provide when writing a bug report?

You should always provide at least the following information:

Apache httpd and OpenSSL version information
The Apache version can be determined by running httpd -v. The OpenSSL version can be determined by running openssl version. Alternatively, if you have Lynx installed, you can run the command lynx -mime_header http://localhost/ | grep Server to gather this information in a single step.
The details on how you built and installed Apache httpd and OpenSSL
For this you can provide a logfile of your terminal session which shows the configuration and install steps. If this is not possible, you should at least provide the configure command line you used.
In case of core dumps please include a Backtrace
If your Apache httpd dumps its core, please attach a stack-frame ``backtrace'' (see below for information on how to get this). This information is required in order to find a reason for your core dump.
A detailed description of your problem
Don't laugh, we really mean it! Many problem reports don't include a description of what the actual problem is. Without this, it's very difficult for anyone to help you. So, it's in your own interest (you want the problem be solved, don't you?) to include as much detail as possible, please. Of course, you should still include all the essentials above too.

I had a core dump, can you help me?

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.

How do I get a backtrace, to help find the reason for my core dump?

Following are the steps you will need to complete, to get a backtrace:

  1. Make sure you have debugging symbols available, at least in Apache. On platforms where you use GCC/GDB, you will have to build Apache+mod_ssl with ``OPTIM="-g -ggdb3"'' to get this. On other platforms at least ``OPTIM="-g"'' is needed.
  2. Start the server and try to reproduce the core-dump. For this you may want to use a directive like ``CoreDumpDirectory /tmp'' to make sure that the core-dump file can be written. This should result in a /tmp/core or /tmp/httpd.core file. If you don't get one of these, try running your server under a non-root UID. Many modern kernels do not allow a process to dump core after it has done a setuid() (unless it does an exec()) for security reasons (there can be privileged information left over in memory). If necessary, you can run /path/to/httpd -X manually to force Apache to not fork.
  3. Analyze the core-dump. For this, run gdb /path/to/httpd /tmp/httpd.core or a similar command. In GDB, all you have to do then is to enter bt, and voila, you get the backtrace. For other debuggers consult your local debugger manual.


How-To / Tutorials - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

How-To / Tutorials

How-To / Tutorials

Authentication and Authorization

Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.

See: Authentication, Authorization

Access Control

Access control refers to the process of restricting, or granting access to a resource based on arbitrary criteria. There are a variety of different ways that this can be accomplished.

See: Access Control

Dynamic Content with CGI

The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is a simple way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.

See: CGI: Dynamic Content

.htaccess files

.htaccess files provide a way to make configuration changes on a per-directory basis. A file, containing one or more configuration directives, is placed in a particular document directory, and the directives apply to that directory, and all subdirectories thereof.

See: .htaccess files

Introduction to Server Side Includes

SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.

See: Server Side Includes (SSI)

Per-user web directories

On systems with multiple users, each user can be permitted to have a web site in their home directory using the UserDir directive. Visitors to a URL http://example.com/~username/ will get content out of the home directory of the user "username", out of the subdirectory specified by the UserDir directive.

See: User web directories (public_html)

Reverse Proxy guide

Apache httpd has extensive capabilities as a reverse proxy server using the ProxyPass directive as well as BalancerMember to create sophisticated reverse proxying implementations which provide for high-availability, load balancing and failover, cloud-based clustering and dynamic on-the-fly reconfiguration.

See: Reverse proxy guide

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Kimlik Doğrulama ve Yetkilendirme - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Nasıllar ve Öğreticiler

Kimlik Doğrulama ve Yetkilendirme

Kimlik Doğrulama istediğiniz kişileri teyid etme işlemidir. Yetkilendirme ise kişilerin nereye gireceklerine ve hangi bilgiye ulaşacaklarına müsaade edilmesi işlemidir.

Genel erişim denetimi için Erişim Denetimi Nasıl belgesine bakınız.

İlgili modüller ve Yönergeler

Kimlik Doğrulama ve yetkilendirme işlemi ile ilgili üç tür modül vardır. Genellikle her bir gruptan en az bir modül seçeceksiniz.

  • Kimlik Doğrulama türü (bkz. AuthType yönergesi)
    • mod_auth_basic
    • mod_auth_digest
  • Kimlik Doğrulayıcı (bkz. AuthBasicProvider ve AuthDigestProvider yönergeleri)
    • mod_authn_anon
    • mod_authn_dbd
    • mod_authn_dbm
    • mod_authn_file
    • mod_authnz_ldap
    • mod_authn_socache
  • Yetkilendirme (bkz. Require yönergesi)
    • mod_authnz_ldap
    • mod_authz_dbd
    • mod_authz_dbm
    • mod_authz_groupfile
    • mod_authz_host
    • mod_authz_owner
    • mod_authz_user

Bu modüllere ek olarak, mod_authn_core ve mod_authz_core modülleri bulunur. Bu modüller yetkilendirme modüllerinin çekirdeğini oluşturan temel yönergeleri gerçekler.

mod_authnz_ldap modülü kimlik doğrulama ve yetkilendirme işlemlerinin ikisini birden gerçekleştirir. mod_authz_host modülü bu işlemleri sunucu adına, IP adresine ve isteğin karekteristiğine bağlı olarak gerçekleştirir. Ancak kimlik doğrulama sisteminin bir parçası değildir. mod_access ile geriye uyumluluk için mod_access_compat diye bir modül daha vardır.

Muhtemelen göz atmak isteyeceğiniz Erişim Denetimi nasıl belgesi, sunucuya erişimlerin çeşitli yollarından bahsetmektedir.

Giriş

Sitenizde sadece küçük bir grup insana hitap eden ya da hassas bilgileriniz varsa, bu makaledeki teknikleri kullanarak dilediğiniz kişilerin sadece dilediğiniz sayfaları görüntülemesini sağlayabilirsiniz.

Bu makale sitenizin bazı parçalarını korumak için kullanacağınız "standart" yolları içermektedir.

Bilginize:

Eğer bilgileriniz gerçekten gizliliğe ihtiyaç duyuyorsa kimlik doğrulamasına ilaveten mod_ssl modülünü de kullanabilirsiniz.

Ön gereksinimler

Bu makalede bahsi geçen yönergeler ya ana sunucu yapılandırma dosyasında (genellikle <Directory> bölümünde) ya da dizin içi yapılandırma dosyalarında (.htaccess dosyaları) bulunmak zorundadır.

Eğer .htaccess dosyalarını kullanmayı tasarlıyorsanız, kimlik doğrulama yönergelerine bu dosyaların içine koymaya izin veren sunucu yapılandırmasına ihtiyacınız olacaktır. Bunun için, dizin içi yapılandırma dosyalarının içine hangi yönergelerin konacağını belirleyen AllowOverride yönergesi kullanılır.

Kimlik doğrulamadan sözettiğimize göre, aşağıda gösterilen şekilde bir AllowOverride yönergesine ihtiyacınız olacaktır:

AllowOverride AuthConfig

Yönergeleri doğrudan ana sunucunun yapılandırma dosyasına koyacaksanız bu dosyaya yazma izniniz olmalıdır.

Bazı dosyaların nerede saklandığını bilmek için sunucunun dizin yapısı hakkında biraz bilgi sahibi olmanız gerekmektedir. Bu çok da zor olmamakla birlikte bu noktaya gelindiğinde konuyu netleştireceğiz.

Ayrıca mod_authn_core ve mod_authz_core modülleri ya httpd çalıştırılabilirinin içinde derlenmiş olmalı ya da httpd.conf yapılandırma dosyası ile yüklenmelidir. Bu iki modül HTTP sunucusunda kimlik doğrulama ve yetkilendirme kullanımı ve yapılandırması için büyük öneme sahip temel yönergeleri ve işlevselliği sağlar.

Çalışmaya Başlama

Burada, sunucu üzerindeki bir dizini parolayla korumak için gereken temel bilgiler verilecektir.

İlk olarak bir parola dosyası oluşturmalısınız. Bunu nasıl yapacağınız, özellikle, seçtiğiniz kimlik doğrulayıcıya göre değişiklik gösterir. Bunun üzerinde ileride daha fazla duracağız. Başlangıç için parolaları bir metin dosyasında tutacağız.

Bu dosya belge kök dizini altında olmamalıdır. Böylece başkaları parola dosyasını indiremezler. Örneğin belgeleriniz /usr/local/apache/htdocs üzerinden sunuluyorsa parola dosyanızı /usr/local/apache/passwd dizininde tutabilirsiniz.

Dosyayı oluşturmak için Apache ile gelen htpasswd uygulamasını kullanacağız. Bu uygulama Apache'nin kurulumunda belirtilen bin dizininde bulunur. Eğer Apache'yi üçüncü parti paketlerden kurduysanız, çalıştırılabilir dosyaların bulunduğu yollar üzerinde olmalıdır.

Bir dosya oluşturmak için şunları yazın:

htpasswd -c /usr/local/apache/passwd/passwords umut

htpasswd size parola soracaktır arkasından da teyit etmek için parolayı tekrar girmenizi isteyecektir:

# htpasswd -c /usr/local/apache/passwd/passwords umut
New password: parolam
Re-type new password: parolam
Adding password for user umut

Eğer htpasswd normal yollar üzerinde değilse çalıştırmak için dosyanın bulunduğu tam yeri belirtmeniz gerekecektir. Dosyanın öntanımlı kurulum yeri: /usr/local/apache2/bin/htpasswd

Bundan sonra, sunucuyu, parola sorması için ve kimlerin erişim izni olacağını belirlemek için yapılandıracaksınız. Bu işlemi httpd.confdosyasını düzenleyerek ya da bir .htaccess dosyası kullanarak yapabilirsiniz. Örneğin, /usr/local/apache/htdocs/secret dizinini korumayı amaçlıyorsanız, şu yönergeleri kullanabilirsiniz. Bu yönergeleri /usr/local/apache/htdocs/secret/.htaccess dosyası içine veya httpd.conf içindeki <Directory "/usr/local/apache/htdocs/secret"> bölümüne koyabilirsiniz.

AuthType Basic
AuthName "Gizli Dosyalar"
# (Aşağıdaki satırın kullanımı isteğe bağlıdır)
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
Require user umut

Bu yönergeleri tek tek inceleyelim. AuthType yönergesi kullanıcının kimliğini doğrulamakta kullanılacak yöntemi seçer. En çok kullanılan yöntem Basic'tir ve bu yöntem mod_auth_basic modülüyle gerçeklenmiştir. Temel (Basic) kimlik doğrulamasıyla gönderilen parolanın şifrelenmeyeceğini unutmayın. Bu yöntem, bu sebepten dolayı mod_ssl eşliğinde kullanılmadığı sürece yüksek hassasiyete sahip bilgiler için kullanılmamalıdır. Apache bir başka kimlik doğrulama yöntemini daha destekler: AuthType Digest. Bu yöntem mod_auth_digest tarafından gerçeklenmişti ve çok daha güvenli olacağı düşünülmüştü. Bu artık geçerliliğini yitirdiğinden bağlantının bundan böyle mod_ssl ile şifrelenmesi gerekmektedir.

AuthName yönergesi ile kimlik doğrulamada kullanılacak Saha da belirtilebilir. Saha kullanımının, başlıca iki işlevi vardır. Birincisi, istemci sıklıkla bu bilgiyi kullanıcıya parola diyalog kutusunun bir parçası olarak sunar. İkincisi, belirtilen kimlik doğrulamalı alan için gönderilecek parolayı belirlerken istemci tarafından kullanılır.

Örneğin, bir istemcinin "Gizli Dosyalar" alanında kimliği doğrulanmış olsun. Aynı sunucu üzerinde "Gizli Dosyalar" Sahası olarak belirlenmiş alanlarda aynı parola özdevinimli olarak yinelenecektir. Böylece parola bir kere girilerek aynı Sahayı paylaşan çok sayıda kısıtlanmış alana ulaşırken oluşacak gecikmeden kullanıcı korunmuş olur. Güvenlik gerekçelerinden dolayı, her sunucu adı değiştirilişinde istemcinin parolayı yeniden sorması gerekir.

AuthBasicProvider yönergesinin öntanımlı değeri file olduğundan, bu durumda, bu yönergenin kullanımı isteğe bağlıdır. Ancak, eğer kimlik doğrulaması için mod_authn_dbm ya da mod_authn_dbd gibi farklı bir kaynak seçecekseniz bu yönergeyi kullanmanız gerekecektir.

AuthUserFile yönergesi htpasswd ile oluşturduğumuz parola dosyasının yerini belirtmek için kullanılır. Eğer çok sayıda kullanıcınız varsa her bir kullanıcıyı her kimlik doğrulama isteği için kimlik bilgilerini bir metin dosyasında aramak gayet yavaş olacaktır. Apache, kullanıcı bilgilerini hızlı bir veritabanı dosyasında depolama özelliğine de sahiptir. Bu amaçla, mod_authn_dbm modülünün AuthDBMUserFile yönergesi kullanılabilir. Bu dosyalar dbmmanage ve htdbm programı ile oluşturulabilir ve değiştirilebilir. Apache modülleri Veritabanı içindeki üçüncü parti modüllerinde çok sayıda başka kimlik doğrulama türü de vardır.

Son olarak Require yönergesi, sunucunun bu bölgesine erişimine izin verilen kullanıcıları ayarlama işleminin kimlik doğrulamasıyla ilgili kısmını sağlar. Bir sonraki bölümde Require yönergesini kullanmanın çeşitli yoları üzerinde duracağız.

Birden çok kişiye izin vermek

Yukarıdaki yönergelerle bir dizinde sadece bir kişiye (umut adlı kullanıcıya) izin verir. Çoğunlukla birden çok kişiye izin verilmesi istenir. Bu durumda AuthGroupFile yönergesi devreye girer.

Eğer birden çok kişiye izin vermek istiyorsanız içinde kullanıcı isimlerinin olduğu bir grup dosyası oluşturmalısınız. Bu dosyanın biçemi gayet basittir ve bunu herhangi bir metin düzenleyici ile oluşturabilirsiniz. Bu dosyanın içeriği aşağıdaki gibi görünecektir:

GroupName: umut samet engin kubilay

Dosya, sadece, boşluklarla birbirinden ayrılmış gurup üyelerinin isimlerinden oluşan uzun bir liste içerir.

Varolan parola dosyasına bir kullanıcı eklemek için şunu yazın:

htpasswd /usr/local/apache/passwd/passwords birey

Evvelce almış olduğunuz yanıtı yine alacaksınız ama bu sefer yeni bir dosya oluşturulmak yerine var olan bir dosyaya eklenecektir. (Yeni bir parola dosyası oluşturmak için -c seçeneği kullanılır).

Şimdi, .htaccess dosyanızı veya <Directory> bölümünüzü aşağıda görüldüğü şekilde değiştirebilirsiniz:

AuthType Basic
AuthName "Davete Binaen"
# Satır isteğe bağlıdır:
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
AuthGroupFile "/usr/local/apache/passwd/groups"
Require group Grupismi

Artık, Grupismi gurubunda listelenmiş ve password dosyasında kaydı olan kişiye, parolayı doğru yazdığı takdirde izin verilecektir.

Çoklu kullanıcıya izin veren biraz daha az kullanılan başka bir yol daha mevcuttur. Bir gurup dosyası oluşturmaktansa, şu yönergeyi kullanabilirsiniz:

Require valid-user

Require user umut satırı ile parola dosyasında listelenmiş ve parolayı doğru olarak giren herhangi bir kişiye izin vermektense, her grup için ayrı bir parola dosyası tutarak grup davranışını taklit edebilirsiniz.

Olası Sorunlar

Temel kimlik doğrulama yolu belirtildiği için, sunucuya yaptığınız her belge istediğinde kullanıcı adınızın ve parolanızın doğrulanması gerekir. Hatta aynı sayfayı yeniden yüklerken ya da sayfadaki her bir resim için bu yapılmalıdır (şayet korunmakta olan bir dizinden geliyorsa). Bu işlem hızı azaltacaktır. Yavaşlama miktarı parola dosyanızın büyüklüğü ile orantılı olacaktır, çünkü bu işlem sırasında dosya açılacak ve kullanıcıların arasında isminiz bulunana kadar liste aşağı doğru taranacaktır. Bu işlem sayfa her yüklenişinde tekrar edilecektir.

Buradan çıkacak sonuç, bir parola dosyasına konulan kullanıcı sayısında bir üst sınır olması gerekliliğidir. Bu sınır sunucunuzun başarımına bağlı olarak değişiklik gösterir. Bir kaç yüz kayıtın üstünde giriş yaptığınızda hız düşüşünü gözlemlebilirsiniz İşte bu anda kimlik doğrulama için başka bir yöntem aramaya başlarsınız.

Diğer parola depolama yöntemleri

Parolaları basit bir metin dosyasında depolamak yukarıda bahsedilen sorunlara yol açtığından parolaları başka bir yerde depolamayı düşünebilirsiniz; örneğin bir veritabanında.

mod_authn_dbm ve mod_authn_dbd modülleri bunu mümkün kılan iki modüldür. Depolama yönemi olarak AuthBasicProvider file yerine, dbm veya dbd kullanabilirsiniz.

Bir metin dosyası yerine bir dbm dosyası kullanım örneği:

<Directory "/www/docs/private">
    AuthName "Private"
    AuthType Basic
    AuthBasicProvider dbm
    AuthDBMUserFile "/www/passwords/passwd.dbm"
    Require valid-user
</Directory>

Başka seçenekler de mümkündür. Ayrınılar için mod_authn_dbm belgesine başvurun.

Birden çok tedarikçi kullanmak

Kimlik doğrulama ve yetkilendirme mimarisine dayalı yeni tedarikçiyi kullanarak tek bir yetkilendirme ya da kimlik doğrulama yöntemine kilitlenip kalmayacaksınız. Aslında birden çok tedarikçi ihtiyacınıza cevap vermek için bir arada kullanılabilir. Aşağıdaki örnekte dosya ve LDAP tabanlı kimlik doğrulama tedarikçileri bir arada kullanılmıştır.

<Directory "/www/docs/private">
    AuthName "Private"
    AuthType Basic
    AuthBasicProvider file ldap
    AuthUserFile "/usr/local/apache/passwd/passwords"
    AuthLDAPURL ldap://ldaphost/o=yourorg
    Require valid-user
</Directory>

Bu örnekte dosya tedarikçisi, ilk olarak kullanıcının kimliğini doğrulamaya teşebbüs edecektir. Kullanıcının kimliği doğrulanamıyorsa LDAP tedarikçisi çağırılır. Eğer kurumunuz birden çok kimlik doğrulama tedarikçisini yürürlüğe koyuyorsa bu, kimlik doğrulama faaliyet alanının genişletilmesini sağlar. Diğer kimlik kanıtlama ve yetkilendirme senaryoları tek bir kimlik doğrulaması ile birden fazla yetkilendirme türüne izin verebilir.

Çok sayıda kimlik doğrulama tedarikçisi uygulamaya konulabileceği gibi, çok sayıda yetkilendirme yöntemi de kullanılabilir. Bu örnekte dosya için hem dosyalı hem de LDAP grup kimlik doğrulaması kullanılmıştır.

<Directory "/www/docs/private">
    AuthName "Private"
    AuthType Basic
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    AuthLDAPURL ldap://ldaphost/o=yourorg
    AuthGroupFile "/usr/local/apache/passwd/groups"
    Require group GroupName
    Require ldap-group cn=mygroup,o=yourorg
</Directory>

Kimlik doğrulama konusunu biraz daha genişletirsek, <RequireAll> ve <RequireAny> gibi yetkilendirme taşıyıcısı yönergelerle hangi iznin hangi sırayla uygulanacağını belirlenebilir. Yetkilendirme Taşıyıcıları bölümünde bunun bir uygulama örneğini görebilirsiniz.

Yetkilendirmenin biraz ötesi

Tek bir veri deposundan yapılacak tek bir sınamadan çok daha esnek kimlik doğrulaması yapılabilir. Sıralama, mantık ve hangi kimlik doğrulamasının kullanılacağını seçmek mümkündür.

Mantık ve sıralamanın uygulanması

Yetkilendirmenin hangi sırayla uygulanacağı ve nasıl denetleneceği geçmişte biraz gizemli bir konuydu. Apache 2.2'de, tedarikçi tabanlı kimlik doğrulamasının devreye girmesiyle asıl kimlik doğrulama işlemini yetkilendirme ve destek işlevselliğinden ayırmak mümkün oldu. Bunun faydalarından birisi de kimlik doğrulama tedarikçilerinin yapılandırılabilmesi ve auth modülünün kendi yükleme sırasından bağımsız olarak özel bir sırayla çağrılabilmesidir. Bu tedarikçi tabanlı mekanizmanın aynısı yetkilendirmeye de getirilmiştir. Bunun anlamı Require yönergesinde hangi izin yönteminin kullanılması gerektiğinin belirtmesinin yanında hangi sırayla çağırılacaklarının da belirlenebildiğidir. Çok sayıda yetkilendirme yöntemi kullanıldığında, bunlar, Require yönergelerinin yapılandırma dosyasında göründükleri sıra ile çağırılır.

<RequireAll> ve <RequireAny> gibi yetkilendirme taşıyıcısı yönergelerin devreye girmesiyle yetkilendirme yöntemlerinin ne zaman çağırılacağı ve çağırıldığında ve erişime izin verirken hangi kuralların uygulanacağı konusunda denetim yapılandırmanın eline geçmektedir. Karmaşık yetkilendime mantığını ifade etmek için kullanılan bir örneği görmek için Yetkilendirme Taşıyıcıları bölümüne bakınız.

Öntanımlı olarak tüm Require yönergeleri, <RequireAny> taşıyıcı yönergesinin içine konur. Başka bir deyişle eğer belirtilen kimlik doğrulama yöntemlerinden herhangi biri başarılı olursa yetkilendirme de sağlanmış olur.

Erişim denetimi için yetkilendirme tedarikçilerinin kullanımı

Kullanıcı adı ve parolasına göre kimlik doğrulama hikayenin sadece bir bölümüdür. Sıklıkla insanlara kim olduklarına göre değil birşeylere dayanarak izin vermek istersiniz. Örneğin nereden geldikleri gibi.

all, env, host ve ip gibi yetkilendirme tedarikçileri ile, bir belgenin istendiği makinenin IP adresi veya konak ismi gibi bazı özelliklerine dayalı olarak erişime izin verip vermeyeceğinizi belirtebilirsiniz.

Bu tedarikçilerin kullanımı Require yönergesinde açıklanmıştır. Bu yönergeler, isteklerin işlenmesi sırasında yetkilendirme aşamasında çağırılacak yetkilendirme tedarikçilerini kayda geçirir. Örneğin:

Require ip adres

Burada, adres bir IP adresidir (veya kısmi bir IP addresidir)

Require host alan_adı

Burada, alan_adı bir tam nitelikli alan adıdır (ya da kısmi alan adıdır); gerekirse çok sayıda alan adı veya IP adresi de belirtilebilir.

Örneğin, yorum alanını gereksiz iletilerle dolduran birini uzak tutmak istediğinizi varsayalım. Bu kişiyi uzak tutmak için şunları yapabilirsiniz:

<RequireAll>
    Require all granted
    Require not ip 10.252.46.165
</RequireAll>

Bu adresden gelen ziyaretçiler bu yönergedeki içeriği göremeyeceklerdir. Bunun yerine, elinizde IP adresi değil de makine adı varsa şunu kullanabilirsiniz:

<RequireAll>
    Require all granted
    Require not host host.example.com
</RequireAll>

Eğer alan adının tamanıdan gelecek olan bütün erişimleri engellemek isterseniz adresin ya da alan adının bir parçasını belirtin:

<RequireAll>
    Require all granted
    Require not ip 192.168.205
    Require not host phishers.example.com moreidiots.example
    Require not host ke
</RequireAll>

<RequireAll> yönergesini çok sayıda <Require> yönergesi ile birlikte kullanarak, sadece not ile olumsuzlanan tüm koşulları gerçekleyen bağlantılara erişim verilir. Başka bir deyişle, olumsuzlanan koşulları gerçeklemeyen bağlantıların erişimi engellenir.

Erişim denetimi ve geriye uyumluluk

Kimlik doğrulama için tedarik tabanlı mekanizma kullanımının yan etkilerinden birisi, Order, Allow, Deny ve Satisfy erişim denetim yönergelerine artık ihtiyaç duyulmamasıdır. Ancak eski yapılandırmalarla uyumluluğu sağlamak için bu yönergeler mod_access_compat modülüne taşınmıştır.

Kimlik Doğrulama Arabelleği

Zaman zaman kimlik doğrulama ağınızda veya sağlayıcı(ları)nızda kabul edilemez yükler oluşturur. Bu çoğunlukla mod_authn_dbd (veya üçüncü parti/özel sağlayıcıların) kullanıcılarını etkiler. Bununla ilgilenmek için httpd 2.3/2.4, kimlik bilgilerini arabelleklemek ve özgün sağlayıcıların yüklerini azaltmak için yeni bir arabellekleme sağlayıcısı olarak mod_authn_socache modülü ile gelmektedir.

Bu, bazı kullanıcılar için önemli bir başarım artışı sağlayabilir.

Daha fazla bilgi

Daha fazla bilgi için mod_auth_basic ve mod_authz_host modüllerinin belgelerine bakınız. AuthnProviderAlias yönergesi ile bazı yapılandırmalarınızı basitleştirebilirsiniz.

Apache tarafından desteklenen şifrelerle ilgili bilgi için Parola Biçemleri belgesine bakınız.

Erişim Denetimi nasıl belgesinden de bazı bilgiler edinebilirsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Access Control - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Access Control

Access control refers to any means of controlling access to any resource. This is separate from authentication and authorization.

Related Modules and Directives

Access control can be done by several different modules. The most important of these are mod_authz_core and mod_authz_host. Also discussed in this document is access control using mod_rewrite.

Access control by host

If you wish to restrict access to portions of your site based on the host address of your visitors, this is most easily done using mod_authz_host.

The Require provides a variety of different ways to allow or deny access to resources. In conjunction with the RequireAll, RequireAny, and RequireNone directives, these requirements may be combined in arbitrarily complex ways, to enforce whatever your access policy happens to be.

The Allow, Deny, and Order directives, provided by mod_access_compat, are deprecated and will go away in a future version. You should avoid using them, and avoid outdated tutorials recommending their use.

The usage of these directives is:

Require host address
Require ip ip.address

In the first form, address is a fully qualified domain name (or a partial domain name); you may provide multiple addresses or domain names, if desired.

In the second form, ip.address is an IP address, a partial IP address, a network/netmask pair, or a network/nnn CIDR specification. Either IPv4 or IPv6 addresses may be used.

See the mod_authz_host documentation for further examples of this syntax.

You can insert not to negate a particular requirement. Note, that since a not is a negation of a value, it cannot be used by itself to allow or deny a request, as not true does not constitute false. Thus, to deny a visit using a negation, the block must have one element that evaluates as true or false. For example, if you have someone spamming your message board, and you want to keep them out, you could do the following:

<RequireAll>
    Require all granted
    Require not ip 10.252.46.165
</RequireAll>

Visitors coming from that address (10.252.46.165) will not be able to see the content covered by this directive. If, instead, you have a machine name, rather than an IP address, you can use that.

Require not host host.example.com

And, if you'd like to block access from an entire domain, you can specify just part of an address or domain name:

Require not ip 192.168.205
Require not host phishers.example.com moreidiots.example
Require not host gov

Use of the RequireAll, RequireAny, and RequireNone directives may be used to enforce more complex sets of requirements.

Access control by arbitrary variables

Using the <If>, you can allow or deny access based on arbitrary environment variables or request header values. For example, to deny access based on user-agent (the browser type) you might do the following:

<If "%{HTTP_USER_AGENT} == 'BadBot'">
    Require all denied
</If>

Using the Require expr syntax, this could also be written as:

Require expr %{HTTP_USER_AGENT} != 'BadBot'

Warning:

Access control by User-Agent is an unreliable technique, since the User-Agent header can be set to anything at all, at the whim of the end user.

See the expressions document for a further discussion of what expression syntaxes and variables are available to you.

Access control with mod_rewrite

The [F] RewriteRule flag causes a 403 Forbidden response to be sent. Using this, you can deny access to a resource based on arbitrary criteria.

For example, if you wish to block access to a resource between 8pm and 6am, you can do this using mod_rewrite.

RewriteEngine On
RewriteCond "%{TIME_HOUR}" ">=20" [OR]
RewriteCond "%{TIME_HOUR}" "<07"
RewriteRule "^/fridge"     "-" [F]

This will return a 403 Forbidden response for any request after 8pm or before 7am. This technique can be used for any criteria that you wish to check. You can also redirect, or otherwise rewrite these requests, if that approach is preferred.

The <If> directive, added in 2.4, replaces many things that mod_rewrite has traditionally been used to do, and you should probably look there first before resorting to mod_rewrite.

More information

The expression engine gives you a great deal of power to do a variety of things based on arbitrary server variables, and you should consult that document for more detail.

Also, you should read the mod_authz_core documentation for examples of combining multiple access requirements and specifying how they interact.

See also the Authentication and Authorization howto.


Apache Tutorial: Dynamic Content with CGI - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Apache Tutorial: Dynamic Content with CGI

Introduction

Related Modules Related Directives
  • mod_alias
  • mod_cgi
  • AddHandler
  • Options
  • ScriptAlias

The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.

Configuring Apache to permit CGI

In order to get your CGI programs to work properly, you'll need to have Apache configured to permit CGI execution. There are several ways to do this.

Note: If Apache has been built with shared module support you need to ensure that the module is loaded; in your httpd.conf you need to make sure the LoadModule directive has not been commented out. A correctly configured directive may look like this:
LoadModule cgi_module modules/mod_cgi.so

ScriptAlias

The ScriptAlias directive tells Apache that a particular directory is set aside for CGI programs. Apache will assume that every file in this directory is a CGI program, and will attempt to execute it, when that particular resource is requested by a client.

The ScriptAlias directive looks like:

ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"

The example shown is from your default httpd.conf configuration file, if you installed Apache in the default location. The ScriptAlias directive is much like the Alias directive, which defines a URL prefix that is to mapped to a particular directory. Alias and ScriptAlias are usually used for directories that are outside of the DocumentRoot directory. The difference between Alias and ScriptAlias is that ScriptAlias has the added meaning that everything under that URL prefix will be considered a CGI program. So, the example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from the directory /usr/local/apache2/cgi-bin/, and should be treated as a CGI program.

For example, if the URL http://www.example.com/cgi-bin/test.pl is requested, Apache will attempt to execute the file /usr/local/apache2/cgi-bin/test.pl and return the output. Of course, the file will have to exist, and be executable, and return output in a particular way, or Apache will return an error message.

CGI outside of ScriptAlias directories

CGI programs are often restricted to ScriptAlias'ed directories for security reasons. In this way, administrators can tightly control who is allowed to use CGI programs. However, if the proper security precautions are taken, there is no reason why CGI programs cannot be run from arbitrary directories. For example, you may wish to let users have web content in their home directories with the UserDir directive. If they want to have their own CGI programs, but don't have access to the main cgi-bin directory, they will need to be able to run CGI programs elsewhere.

There are two steps to allowing CGI execution in an arbitrary directory. First, the cgi-script handler must be activated using the AddHandler or SetHandler directive. Second, ExecCGI must be specified in the Options directive.

Explicitly using Options to permit CGI execution

You could explicitly use the Options directive, inside your main server configuration file, to specify that CGI execution was permitted in a particular directory:

<Directory "/usr/local/apache2/htdocs/somedir">
    Options +ExecCGI
</Directory>

The above directive tells Apache to permit the execution of CGI files. You will also need to tell the server what files are CGI files. The following AddHandler directive tells the server to treat all files with the cgi or pl extension as CGI programs:

AddHandler cgi-script .cgi .pl

.htaccess files

The .htaccess tutorial shows how to activate CGI programs if you do not have access to httpd.conf.

User Directories

To allow CGI program execution for any file ending in .cgi in users' directories, you can use the following configuration.

<Directory "/home/*/public_html">
    Options +ExecCGI
    AddHandler cgi-script .cgi
</Directory>

If you wish designate a cgi-bin subdirectory of a user's directory where everything will be treated as a CGI program, you can use the following.

<Directory "/home/*/public_html/cgi-bin">
    Options ExecCGI
    SetHandler cgi-script
</Directory>

Writing a CGI program

There are two main differences between ``regular'' programming, and CGI programming.

First, all output from your CGI program must be preceded by a MIME-type header. This is HTTP header that tells the client what sort of content it is receiving. Most of the time, this will look like:

Content-type: text/html

Secondly, your output needs to be in HTML, or some other format that a browser will be able to display. Most of the time, this will be HTML, but occasionally you might write a CGI program that outputs a gif image, or other non-HTML content.

Apart from those two things, writing a CGI program will look a lot like any other program that you might write.

Your first CGI program

The following is an example CGI program that prints one line to your browser. Type in the following, save it to a file called first.pl, and put it in your cgi-bin directory.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";

Even if you are not familiar with Perl, you should be able to see what is happening here. The first line tells Apache (or whatever shell you happen to be running under) that this program can be executed by feeding the file to the interpreter found at the location /usr/bin/perl. The second line prints the content-type declaration we talked about, followed by two carriage-return newline pairs. This puts a blank line after the header, to indicate the end of the HTTP headers, and the beginning of the body. The third line prints the string "Hello, World.". And that's the end of it.

If you open your favorite browser and tell it to get the address

http://www.example.com/cgi-bin/first.pl

or wherever you put your file, you will see the one line Hello, World. appear in your browser window. It's not very exciting, but once you get that working, you'll have a good chance of getting just about anything working.

But it's still not working!

There are four basic things that you may see in your browser when you try to access your CGI program from the web:

The output of your CGI program
Great! That means everything worked fine. If the output is correct, but the browser is not processing it correctly, make sure you have the correct Content-Type set in your CGI program.
The source code of your CGI program or a "POST Method Not Allowed" message
That means that you have not properly configured Apache to process your CGI program. Reread the section on configuring Apache and try to find what you missed.
A message starting with "Forbidden"
That means that there is a permissions problem. Check the Apache error log and the section below on file permissions.
A message saying "Internal Server Error"
If you check the Apache error log, you will probably find that it says "Premature end of script headers", possibly along with an error message generated by your CGI program. In this case, you will want to check each of the below sections to see what might be preventing your CGI program from emitting the proper HTTP headers.

File permissions

Remember that the server does not run as you. That is, when the server starts up, it is running with the permissions of an unprivileged user - usually nobody, or www - and so it will need extra permissions to execute files that are owned by you. Usually, the way to give a file sufficient permissions to be executed by nobody is to give everyone execute permission on the file:

chmod a+x first.pl

Also, if your program reads from, or writes to, any other files, those files will need to have the correct permissions to permit this.

Path information and environment

When you run a program from your command line, you have certain information that is passed to the shell without you thinking about it. For example, you have a PATH, which tells the shell where it can look for files that you reference.

When a program runs through the web server as a CGI program, it may not have the same PATH. Any programs that you invoke in your CGI program (like sendmail, for example) will need to be specified by a full path, so that the shell can find them when it attempts to execute your CGI program.

A common manifestation of this is the path to the script interpreter (often perl) indicated in the first line of your CGI program, which will look something like:

#!/usr/bin/perl

Make sure that this is in fact the path to the interpreter.

When editing CGI scripts on Windows, end-of-line characters may be appended to the interpreter path. Ensure that files are then transferred to the server in ASCII mode. Failure to do so may result in "Command not found" warnings from the OS, due to the unrecognized end-of-line character being interpreted as a part of the interpreter filename.

Missing environment variables

If your CGI program depends on non-standard environment variables, you will need to assure that those variables are passed by Apache.

When you miss HTTP headers from the environment, make sure they are formatted according to RFC 2616, section 4.2: Header names must start with a letter, followed only by letters, numbers or hyphen. Any header violating this rule will be dropped silently.

Program errors

Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make the above two mistakes. The first thing to do is to make sure that your program runs from the command line before testing it via the web server. For example, try:

cd /usr/local/apache2/cgi-bin
./first.pl

(Do not call the perl interpreter. The shell and Apache should find the interpreter using the path information on the first line of the script.)

The first thing you see written by your program should be a set of HTTP headers, including the Content-Type, followed by a blank line. If you see anything else, Apache will return the Premature end of script headers error if you try to run it through the server. See Writing a CGI program above for more details.

Error logs

The error logs are your friend. Anything that goes wrong generates message in the error log. You should always look there first. If the place where you are hosting your web site does not permit you access to the error log, you should probably host your site somewhere else. Learn to read the error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.

Suexec

The suexec support program allows CGI programs to be run under different user permissions, depending on which virtual host or user home directory they are located in. Suexec has very strict permission checking, and any failure in that checking will result in your CGI programs failing with Premature end of script headers.

To check if you are using suexec, run apachectl -V and check for the location of SUEXEC_BIN. If Apache finds an suexec binary there on startup, suexec will be activated.

Unless you fully understand suexec, you should not be using it. To disable suexec, simply remove (or rename) the suexec binary pointed to by SUEXEC_BIN and then restart the server. If, after reading about suexec, you still wish to use it, then run suexec -V to find the location of the suexec log file, and use that log file to find what policy you are violating.

What's going on behind the scenes?

As you become more advanced in CGI programming, it will become useful to understand more about what's happening behind the scenes. Specifically, how the browser and server communicate with one another. Because although it's all very well to write a program that prints "Hello, World.", it's not particularly useful.

Environment variables

Environment variables are values that float around you as you use your computer. They are useful things like your path (where the computer searches for the actual file implementing a command when you type it), your username, your terminal type, and so on. For a full list of your normal, every day environment variables, type env at a command prompt.

During the CGI transaction, the server and the browser also set environment variables, so that they can communicate with one another. These are things like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite), the name of the CGI program that is being run, and so on.

These variables are available to the CGI programmer, and are half of the story of the client-server communication. The complete list of required variables is at Common Gateway Interface RFC.

This simple Perl CGI program will display all of the environment variables that are being passed around. Two similar programs are included in the cgi-bin directory of the Apache distribution. Note that some variables are required, while others are optional, so you may see some variables listed that were not in the official list. In addition, Apache provides many different ways for you to add your own environment variables to the basic ones provided by default.

#!/usr/bin/perl
use strict;
use warnings;

print "Content-type: text/html\n\n";
foreach my $key (keys %ENV) {
    print "$key --> $ENV{$key}<br>";
}

STDIN and STDOUT

Other communication between the server and the client happens over standard input (STDIN) and standard output (STDOUT). In normal everyday context, STDIN means the keyboard, or a file that a program is given to act on, and STDOUT usually means the console or screen.

When you POST a web form to a CGI program, the data in that form is bundled up into a special format and gets delivered to your CGI program over STDIN. The program then can process that data as though it was coming in from the keyboard, or from a file

The "special format" is very simple. A field name and its value are joined together with an equals (=) sign, and pairs of values are joined together with an ampersand (&). Inconvenient characters like spaces, ampersands, and equals signs, are converted into their hex equivalent so that they don't gum up the works. The whole data string might look something like:

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

You'll sometimes also see this type of string appended to a URL. When that is done, the server puts that string into the environment variable called QUERY_STRING. That's called a GET request. Your HTML form specifies whether a GET or a POST is used to deliver the data, by setting the METHOD attribute in the FORM tag.

Your program is then responsible for splitting that string up into useful information. Fortunately, there are libraries and modules available to help you process this data, as well as handle other of the aspects of your CGI program.

CGI modules/libraries

When you write CGI programs, you should consider using a code library, or module, to do most of the grunt work for you. This leads to fewer errors, and faster development.

If you're writing CGI programs in Perl, modules are available on CPAN. The most popular module for this purpose is CGI.pm. You might also consider CGI::Lite, which implements a minimal set of functionality, which is all you need in most programs.

If you're writing CGI programs in C, there are a variety of options. One of these is the CGIC library, from http://www.boutell.com/cgic/.

For more information

The current CGI specification is available in the Common Gateway Interface RFC.

When you post a question about a CGI problem that you're having, whether to a mailing list, or to a newsgroup, make sure you provide enough information about what happened, what you expected to happen, and how what actually happened was different, what server you're running, what language your CGI program was in, and, if possible, the offending code. This will make finding your problem much simpler.

Note that questions about CGI problems should never be posted to the Apache bug database unless you are sure you have found a problem in the Apache source code.


Apache httpd Tutorial: Introduction to Server Side Includes - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Apache httpd Tutorial: Introduction to Server Side Includes

Server-side includes provide a means to add dynamic content to existing HTML documents.

Introduction

Related Modules Related Directives
  • mod_include
  • mod_cgi
  • mod_expires
  • Options
  • XBitHack
  • AddType
  • SetOutputFilter
  • BrowserMatchNoCase

This article deals with Server Side Includes, usually called simply SSI. In this article, I'll talk about configuring your server to permit SSI, and introduce some basic SSI techniques for adding dynamic content to your existing HTML pages.

In the latter part of the article, we'll talk about some of the somewhat more advanced things that can be done with SSI, such as conditional statements in your SSI directives.

What are SSI?

SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.

For example, you might place a directive into an existing HTML page, such as:

<!--#echo var="DATE_LOCAL" -->

And, when the page is served, this fragment will be evaluated and replaced with its value:

Tuesday, 15-Jan-2013 19:28:54 EST

The decision of when to use SSI, and when to have your page entirely generated by some program, is usually a matter of how much of the page is static, and how much needs to be recalculated every time the page is served. SSI is a great way to add small pieces of information, such as the current time - shown above. But if a majority of your page is being generated at the time that it is served, you need to look for some other solution.

Configuring your server to permit SSI

To permit SSI on your server, you must have the following directive either in your httpd.conf file, or in a .htaccess file:

Options +Includes

This tells Apache that you want to permit files to be parsed for SSI directives. Note that most configurations contain multiple Options directives that can override each other. You will probably need to apply the Options to the specific directory where you want SSI enabled in order to assure that it gets evaluated last.

Not just any file is parsed for SSI directives. You have to tell Apache which files should be parsed. There are two ways to do this. You can tell Apache to parse any file with a particular file extension, such as .shtml, with the following directives:

        AddType text/html .shtml

        AddOutputFilter INCLUDES .shtml

One disadvantage to this approach is that if you wanted to add SSI directives to an existing page, you would have to change the name of that page, and all links to that page, in order to give it a .shtml extension, so that those directives would be executed.

The other method is to use the XBitHack directive:

XBitHack on

XBitHack tells Apache to parse files for SSI directives if they have the execute bit set. So, to add SSI directives to an existing page, rather than having to change the file name, you would just need to make the file executable using chmod.

chmod +x pagename.html

A brief comment about what not to do. You'll occasionally see people recommending that you just tell Apache to parse all .html files for SSI, so that you don't have to mess with .shtml file names. These folks have perhaps not heard about XBitHack. The thing to keep in mind is that, by doing this, you're requiring that Apache read through every single file that it sends out to clients, even if they don't contain any SSI directives. This can slow things down quite a bit, and is not a good idea.

Of course, on Windows, there is no such thing as an execute bit to set, so that limits your options a little.

In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower perceived client performance. There are two ways to solve this:

  1. Use the XBitHack Full configuration. This tells Apache to determine the last modified date by looking only at the date of the originally requested file, ignoring the modification date of any included files.
  2. Use the directives provided by mod_expires to set an explicit expiration time on your files, thereby letting browsers and proxies know that it is acceptable to cache them.

Basic SSI directives

SSI directives have the following syntax:

<!--#function attribute=value attribute=value ... -->

It is formatted like an HTML comment, so if you don't have SSI correctly enabled, the browser will ignore it, but it will still be visible in the HTML source. If you have SSI correctly configured, the directive will be replaced with its results.

The function can be one of a number of things, and we'll talk some more about most of these in the next installment of this series. For now, here are some examples of what you can do with SSI

Today's date

<!--#echo var="DATE_LOCAL" -->

The echo function just spits out the value of a variable. There are a number of standard variables, which include the whole set of environment variables that are available to CGI programs. Also, you can define your own variables with the set function.

If you don't like the format in which the date gets printed, you can use the config function, with a timefmt attribute, to modify that formatting.

<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->

Modification date of the file

This document last modified <!--#flastmod file="index.html" -->

This function is also subject to timefmt format configurations.

Including the results of a CGI program

This is one of the more common uses of SSI - to output the results of a CGI program, such as everybody's favorite, a ``hit counter.''

<!--#include virtual="/cgi-bin/counter.pl" -->

Additional examples

Following are some specific examples of things you can do in your HTML documents with SSI.

When was this document modified?

Earlier, we mentioned that you could use SSI to inform the user when the document was most recently modified. However, the actual method for doing that was left somewhat in question. The following code, placed in your HTML document, will put such a time stamp on your page. Of course, you will have to have SSI correctly enabled, as discussed above.

<!--#config timefmt="%A %B %d, %Y" -->
This file last modified <!--#flastmod file="ssi.shtml" -->

Of course, you will need to replace the ssi.shtml with the actual name of the file that you're referring to. This can be inconvenient if you're just looking for a generic piece of code that you can paste into any file, so you probably want to use the LAST_MODIFIED variable instead:

<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->

For more details on the timefmt format, go to your favorite search site and look for strftime. The syntax is the same.

Including a standard footer

If you are managing any site that is more than a few pages, you may find that making changes to all those pages can be a real pain, particularly if you are trying to maintain some kind of standard look across all those pages.

Using an include file for a header and/or a footer can reduce the burden of these updates. You just have to make one footer file, and then include it into each page with the include SSI command. The include function can determine what file to include with either the file attribute, or the virtual attribute. The file attribute is a file path, relative to the current directory. That means that it cannot be an absolute file path (starting with /), nor can it contain ../ as part of that path. The virtual attribute is probably more useful, and should specify a URL relative to the document being served. It can start with a /, but must be on the same server as the file being served.

<!--#include virtual="/footer.html" -->

I'll frequently combine the last two things, putting a LAST_MODIFIED directive inside a footer file to be included. SSI directives can be contained in the included file, and includes can be nested - that is, the included file can include another file, and so on.

What else can I config?

In addition to being able to config the time format, you can also config two other things.

Usually, when something goes wrong with your SSI directive, you get the message

[an error occurred while processing this directive]

If you want to change that message to something else, you can do so with the errmsg attribute to the config function:

<!--#config errmsg="[It appears that you don't know how to use SSI]" -->

Hopefully, end users will never see this message, because you will have resolved all the problems with your SSI directives before your site goes live. (Right?)

And you can config the format in which file sizes are returned with the sizefmt attribute. You can specify bytes for a full count in bytes, or abbrev for an abbreviated number in Kb or Mb, as appropriate.

Executing commands

I expect that I'll have an article some time in the coming months about using SSI with small CGI programs. For now, here's something else that you can do with the exec function. You can actually have SSI execute a command using the shell (/bin/sh, to be precise - or the DOS shell, if you're on Win32). The following, for example, will give you a directory listing.

<pre>
<!--#exec cmd="ls" -->
</pre>

or, on Windows

<pre>
<!--#exec cmd="dir" -->
</pre>

You might notice some strange formatting with this directive on Windows, because the output from dir contains the string ``<dir>'' in it, which confuses browsers.

Note that this feature is exceedingly dangerous, as it will execute whatever code happens to be embedded in the exec tag. If you have any situation where users can edit content on your web pages, such as with a ``guestbook'', for example, make sure that you have this feature disabled. You can allow SSI, but not the exec feature, with the IncludesNOEXEC argument to the Options directive.

Advanced SSI techniques

In addition to spitting out content, Apache SSI gives you the option of setting variables, and using those variables in comparisons and conditionals.

Setting variables

Using the set directive, you can set variables for later use. We'll need this later in the discussion, so we'll talk about it here. The syntax of this is as follows:

<!--#set var="name" value="Rich" -->

In addition to merely setting values literally like that, you can use any other variable, including environment variables or the variables discussed above (like LAST_MODIFIED, for example) to give values to your variables. You will specify that something is a variable, rather than a literal string, by using the dollar sign ($) before the name of the variable.

<!--#set var="modified" value="$LAST_MODIFIED" -->

To put a literal dollar sign into the value of your variable, you need to escape the dollar sign with a backslash.

<!--#set var="cost" value="\$100" -->

Finally, if you want to put a variable in the midst of a longer string, and there's a chance that the name of the variable will run up against some other characters, and thus be confused with those characters, you can place the name of the variable in braces, to remove this confusion. (It's hard to come up with a really good example of this, but hopefully you'll get the point.)

<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->

Conditional expressions

Now that we have variables, and are able to set and compare their values, we can use them to express conditionals. This lets SSI be a tiny programming language of sorts. mod_include provides an if, elif, else, endif structure for building conditional statements. This allows you to effectively generate multiple logical pages out of one actual page.

The structure of this conditional construct is:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

A test_condition can be any sort of logical comparison - either comparing values to one another, or testing the ``truth'' of a particular value. (A given string is true if it is nonempty.) For a full list of the comparison operators available to you, see the mod_include documentation.

For example, if you wish to customize the text on your web page based on the time of day, you could use the following recipe, placed in the HTML page:

Good <!--#if expr="%{TIME_HOUR} <12" -->
morning!
<!--#else -->
afternoon!
<!--#endif -->

Any other variable (either ones that you define, or normal environment variables) can be used in conditional statements. See Expressions in Apache HTTP Server for more information on the expression evaluation engine.

With Apache's ability to set environment variables with the SetEnvIf directives, and other related directives, this functionality can let you do a wide variety of dynamic content on the server side without resorting a full web application.

Conclusion

SSI is certainly not a replacement for CGI, or other technologies used for generating dynamic web pages. But it is a great way to add small amounts of dynamic content to pages, without doing a lot of extra work.


Apache HTTP Server Tutorial: .htaccess files - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Apache HTTP Server Tutorial: .htaccess files

.htaccess files provide a way to make configuration changes on a per-directory basis.

.htaccess files

Related Modules Related Directives
  • core
  • mod_authn_file
  • mod_authz_groupfile
  • mod_cgi
  • mod_include
  • mod_mime
  • AccessFileName
  • AllowOverride
  • Options
  • AddHandler
  • SetHandler
  • AuthType
  • AuthName
  • AuthUserFile
  • AuthGroupFile
  • Require
You should avoid using .htaccess files completely if you have access to httpd main server config file. Using .htaccess files slows down your Apache http server. Any directive that you can include in a .htaccess file is better set in a Directory block, as it will have the same effect with better performance.

What they are/How to use them

.htaccess files (or "distributed configuration files") provide a way to make configuration changes on a per-directory basis. A file, containing one or more configuration directives, is placed in a particular document directory, and the directives apply to that directory, and all subdirectories thereof.

Note:

If you want to call your .htaccess file something else, you can change the name of the file using the AccessFileName directive. For example, if you would rather call the file .config then you can put the following in your server configuration file:

AccessFileName ".config"

In general, .htaccess files use the same syntax as the main configuration files. What you can put in these files is determined by the AllowOverride directive. This directive specifies, in categories, what directives will be honored if they are found in a .htaccess file. If a directive is permitted in a .htaccess file, the documentation for that directive will contain an Override section, specifying what value must be in AllowOverride in order for that directive to be permitted.

For example, if you look at the documentation for the AddDefaultCharset directive, you will find that it is permitted in .htaccess files. (See the Context line in the directive summary.) The Override line reads FileInfo. Thus, you must have at least AllowOverride FileInfo in order for this directive to be honored in .htaccess files.

Example:

Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo

If you are unsure whether a particular directive is permitted in a .htaccess file, look at the documentation for that directive, and check the Context line for ".htaccess".

When (not) to use .htaccess files

In general, you should only use .htaccess files when you don't have access to the main server configuration file. There is, for example, a common misconception that user authentication should always be done in .htaccess files, and, in more recent years, another misconception that mod_rewrite directives must go in .htaccess files. This is simply not the case. You can put user authentication configurations in the main server configuration, and this is, in fact, the preferred way to do things. Likewise, mod_rewrite directives work better, in many respects, in the main server configuration.

.htaccess files should be used in a case where the content providers need to make configuration changes to the server on a per-directory basis, but do not have root access on the server system. In the event that the server administrator is not willing to make frequent configuration changes, it might be desirable to permit individual users to make these changes in .htaccess files for themselves. This is particularly true, for example, in cases where ISPs are hosting multiple user sites on a single machine, and want their users to be able to alter their configuration.

However, in general, use of .htaccess files should be avoided when possible. Any configuration that you would consider putting in a .htaccess file, can just as effectively be made in a <Directory> section in your main server configuration file.

There are two main reasons to avoid the use of .htaccess files.

The first of these is performance. When AllowOverride is set to allow the use of .htaccess files, httpd will look in every directory for .htaccess files. Thus, permitting .htaccess files causes a performance hit, whether or not you actually even use them! Also, the .htaccess file is loaded every time a document is requested.

Further note that httpd must look for .htaccess files in all higher-level directories, in order to have a full complement of directives that it must apply. (See section on how directives are applied.) Thus, if a file is requested out of a directory /www/htdocs/example, httpd must look for the following files:

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess

And so, for each file access out of that directory, there are 4 additional file-system accesses, even if none of those files are present. (Note that this would only be the case if .htaccess files were enabled for /, which is not usually the case.)

In the case of RewriteRule directives, in .htaccess context these regular expressions must be re-compiled with every request to the directory, whereas in main server configuration context they are compiled once and cached. Additionally, the rules themselves are more complicated, as one must work around the restrictions that come with per-directory context and mod_rewrite. Consult the Rewrite Guide for more detail on this subject.

The second consideration is one of security. You are permitting users to modify server configuration, which may result in changes over which you have no control. Carefully consider whether you want to give your users this privilege. Note also that giving users less privileges than they need will lead to additional technical support requests. Make sure you clearly tell your users what level of privileges you have given them. Specifying exactly what you have set AllowOverride to, and pointing them to the relevant documentation, will save yourself a lot of confusion later.

Note that it is completely equivalent to put a .htaccess file in a directory /www/htdocs/example containing a directive, and to put that same directive in a Directory section <Directory "/www/htdocs/example"> in your main server configuration:

.htaccess file in /www/htdocs/example:

Contents of .htaccess file in /www/htdocs/example

AddType text/example ".exm"

Section from your httpd.conf file

<Directory "/www/htdocs/example">
    AddType text/example ".exm"
</Directory>

However, putting this configuration in your server configuration file will result in less of a performance hit, as the configuration is loaded once when httpd starts, rather than every time a file is requested.

The use of .htaccess files can be disabled completely by setting the AllowOverride directive to none:

AllowOverride None

How directives are applied

The configuration directives found in a .htaccess file are applied to the directory in which the .htaccess file is found, and to all subdirectories thereof. However, it is important to also remember that there may have been .htaccess files in directories higher up. Directives are applied in the order that they are found. Therefore, a .htaccess file in a particular directory may override directives found in .htaccess files found higher up in the directory tree. And those, in turn, may have overridden directives found yet higher up, or in the main server configuration file itself.

Example:

In the directory /www/htdocs/example1 we have a .htaccess file containing the following:

Options +ExecCGI

(Note: you must have "AllowOverride Options" in effect to permit the use of the "Options" directive in .htaccess files.)

In the directory /www/htdocs/example1/example2 we have a .htaccess file containing:

Options Includes

Because of this second .htaccess file, in the directory /www/htdocs/example1/example2, CGI execution is not permitted, as only Options Includes is in effect, which completely overrides any earlier setting that may have been in place.

Merging of .htaccess with the main configuration files

As discussed in the documentation on Configuration Sections, .htaccess files can override the <Directory> sections for the corresponding directory, but will be overridden by other types of configuration sections from the main configuration files. This fact can be used to enforce certain configurations, even in the presence of a liberal AllowOverride setting. For example, to prevent script execution while allowing anything else to be set in .htaccess you can use:

<Directory "/www/htdocs">
    AllowOverride All
</Directory>

<Location "/">
    Options +IncludesNoExec -ExecCGI

</Location>
This example assumes that your DocumentRoot is /www/htdocs.

Authentication example

If you jumped directly to this part of the document to find out how to do authentication, it is important to note one thing. There is a common misconception that you are required to use .htaccess files in order to implement password authentication. This is not the case. Putting authentication directives in a <Directory> section, in your main server configuration file, is the preferred way to implement this, and .htaccess files should be used only if you don't have access to the main server configuration file. See above for a discussion of when you should and should not use .htaccess files.

Having said that, if you still think you need to use a .htaccess file, you may find that a configuration such as what follows may work for you.

.htaccess file contents:

AuthType Basic
AuthName "Password Required"
AuthUserFile "/www/passwords/password.file"
AuthGroupFile "/www/passwords/group.file"
Require group admins

Note that AllowOverride AuthConfig must be in effect for these directives to have any effect.

Please see the authentication tutorial for a more complete discussion of authentication and authorization.

Server Side Includes example

Another common use of .htaccess files is to enable Server Side Includes for a particular directory. This may be done with the following configuration directives, placed in a .htaccess file in the desired directory:

Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml

Note that AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any effect.

Please see the SSI tutorial for a more complete discussion of server-side includes.

Rewrite Rules in .htaccess files

When using RewriteRule in .htaccess files, be aware that the per-directory context changes things a bit. In particular, rules are taken to be relative to the current directory, rather than being the original requested URI. Consider the following examples:

# In httpd.conf
RewriteRule "^/images/(.+)\.jpg" "/images/$1.png"

# In .htaccess in root dir
RewriteRule "^images/(.+)\.jpg" "images/$1.png"

# In .htaccess in images/
RewriteRule "^(.+)\.jpg" "$1.png"

In a .htaccess in your document directory, the leading slash is removed from the value supplied to RewriteRule, and in the images subdirectory, /images/ is removed from it. Thus, your regular expression needs to omit that portion as well.

Consult the mod_rewrite documentation for further details on using mod_rewrite.

CGI example

Finally, you may wish to use a .htaccess file to permit the execution of CGI programs in a particular directory. This may be implemented with the following configuration:

Options +ExecCGI
AddHandler cgi-script cgi pl

Alternately, if you wish to have all files in the given directory be considered to be CGI programs, this may be done with the following configuration:

Options +ExecCGI
SetHandler cgi-script

Note that AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any effect.

Please see the CGI tutorial for a more complete discussion of CGI programming and configuration.

Troubleshooting

When you put configuration directives in a .htaccess file, and you don't get the desired effect, there are a number of things that may be going wrong.

Most commonly, the problem is that AllowOverride is not set such that your configuration directives are being honored. Make sure that you don't have a AllowOverride None in effect for the file scope in question. A good test for this is to put garbage in your .htaccess file and reload the page. If a server error is not generated, then you almost certainly have AllowOverride None in effect.

If, on the other hand, you are getting server errors when trying to access documents, check your httpd error log. It will likely tell you that the directive used in your .htaccess file is not permitted.

[Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here

This will indicate either that you've used a directive that is never permitted in .htaccess files, or that you simply don't have AllowOverride set to a level sufficient for the directive you've used. Consult the documentation for that particular directive to determine which is the case.

Alternately, it may tell you that you had a syntax error in your usage of the directive itself.

[Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters

In this case, the error message should be specific to the particular syntax error that you have committed.


Kullanıcı Dizinleri (public_html) - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Nasıllar ve Öğreticiler

Kullanıcı Dizinleri (public_html)

Çok kullanıcılı sistemlerde, UserDir yönergesi ile her kullanıcının kendi ev dizininde bir sitesi olması sağlanabilir. http://example.com/~kullanıcı/ adresinin ziyaretçileri "kullanıcı" isimli kullanıcının ev dizininin içeriğini değil, UserDir yönergesinde belirtilen alt dizinin içeriğini görürler.

Öntanımlı olarak bu dizinlere erişimin etkin olmadığını unutmayınız. UserDir yönergesini kullanırken conf/httpd.conf öntanımlı yapılandırma dosyasındaki

#Include conf/extra/httpd-userdir.conf

satırını etkin hale getirip, gerekiyorsa httpd-userdir.conf dosyasını da düzenleyerek veya ana yapılandırma dosyasında bir Directory bloğu içine uygun yönergeleri yerleştirerek bu dizinlere erişimi etkin hale getirebilirsiniz.

Ayrıca bakınız:

  • URL’lerin Dosya Sistemi ile Eşleştirilmesi

Kullanıcı sayfaları dizinleri

İlgili Modüller İlgili Yönergeler
  • mod_userdir
  • UserDir
  • DirectoryMatch
  • AllowOverride

UserDir ile dosya yolunun belirtilmesi

UserDir yönergesinde kullanıcı sayfalarının yükleneceği dizin belirtilir. Bu yönergeye değeri çeşitli biçimlerde atanabilir.

Başında bölü çizgisi bulunmayan bir dosya yolu belirtilmişse, kullanıcının ev dizinine göreli bir dizin belirtildiği varsayılır. Yapılandırmada şöyle bir satır varsa:

UserDir public_html

http://example.com/~orhan/dosya.html adresine karşılık gelen dosya yolu /home/orhan/public_html/dosya.html olarak çözümlenir.

Eğer başında bölü çizgisi bulunan bir dosya yolu belirtilirse, kullanıcı sayfalarının bu dizinin altında kullanıcı ismini taşıyan dizinlerde bulunacağı varsayılır. Yapılandırmada şöyle bir satır varsa:

UserDir /var/html

http://example.com/~orhan/dosya.html adresine karşılık gelen dosya yolu /var/html/orhan/dosya.html olarak çözümlenir.

Eğer belirtilen dosya yolu bir yıldız imi (*) içeriyorsa yıldız iminin yerine kullanıcı ismi yerleştirilerek elde edilen dosya yolu kullanılır. Yapılandırmada şöyle bir satır varsa:

UserDir /var/html/*/sayfam

http://example.com/~orhan/dosya.html adresine karşılık gelen dosya yolu /var/html/orhan/sayfam/dosya.html olarak çözümlenir.

Çok sayıda dizin veya dizin yolu belirtmek de mümkündür.

UserDir public_html /var/html

http://example.com/~orhan/dosya.html adresini Apache önce /home/orhan/public_html/dosya.html olarak arayacak, bulamazsa /var/siteler/orhan/sayfam/dosya.html olarak arayacak, bulduğunda istenen dosyayı sunacaktır.

Harici adreslere yönlendirme

UserDir yönergesi kullanıcı dizini isteklerini harici adreslere yönlendirmek için de kullanılabilir.

UserDir http://example.org/users/*/

Bu yapılandırmaya göre http://example.com/~bob/abc.html için yapılan bir istek http://example.org/users/bob/abc.html adresine yönlendirilecektir.

Bu özelliği kullanacak kullanıcıların sınırlandırılması

UserDir yönergesinin açıklamasında belirtilen sözdizimini kullanarak bu işlevselliği bazı kullanıcılara yasaklayabilirsiniz:

UserDir disabled root ahmet veli

Bu yapılandırma ile disabled deyiminin bulunduğu satırdaki kullanıcılar dışında kalan bütün kullanıcılar için bu özellik etkin olacaktır. Benzer şekilde, aşağıdaki yapılandırma ile işlevselliğin belli kullanıcılar dışında kullanılmamasını da sağlayabilirsiniz:

      UserDir disabled

      UserDir enabled orhan yasar

Daha fazla örnek için UserDir yönergesinin açıklamasına bakabilirsiniz.

Her kullanıcıya bir CGI dizini tahsis etmek

Her kullanıcıya kendine ait bir CGI dizini vermek isterseniz, bir <Directory> yönergesi ile kullanıcının ev dizinindeki belli bir dizini CGI-etkin duruma getirebilirsiniz.

<Directory "/home/*/public_html/cgi-bin/">
    Options ExecCGI
    SetHandler cgi-script
</Directory>

UserDir yönergesinde public_html belirtildiği varsayımıyla mesela.cgi betiği bu dizinden şöyle bir adresle yüklenebilir:

http://example.com/~orhan/cgi-bin/mesela.cgi

Kullanıcıların yapılandırmayı değiştirmesine izin vermek

Kullanıcıların kendilerine ayrılan bölge içinde sunucu yapılandırmasını değiştirebilmelerine izin vermek isterseniz, .htaccess dosyalarını kullanmalarına izin vermeniz gerekir. Kullanıcının değiştirmesine izin vereceğiniz yönerge türlerini AllowOverride yönergesinde belirtmeyi ihmal etmeyin. .htaccess dosyalarının kullanımı ile ilgili daha ayrıntılı bilgi için .htaccess öğreticisine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Reverse Proxy Guide - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Reverse Proxy Guide

In addition to being a "basic" web server, and providing static and dynamic content to end-users, Apache httpd (as well as most other web servers) can also act as a reverse proxy server, also-known-as a "gateway" server.

In such scenarios, httpd itself does not generate or host the data, but rather the content is obtained by one or several backend servers, which normally have no direct connection to the external network. As httpd receives a request from a client, the request itself is proxied to one of these backend servers, which then handles the request, generates the content and then sends this content back to httpd, which then generates the actual HTTP response back to the client.

There are numerous reasons for such an implementation, but generally the typical rationales are due to security, high-availability, load-balancing and centralized authentication/authorization. It is critical in these implementations that the layout, design and architecture of the backend infrastructure (those servers which actually handle the requests) are insulated and protected from the outside; as far as the client is concerned, the reverse proxy server is the sole source of all content.

A typical implementation is below:

Reverse Proxy

Related Modules Related Directives
  • mod_proxy
  • mod_proxy_balancer
  • mod_proxy_hcheck
  • ProxyPass
  • BalancerMember

Simple reverse proxying

The ProxyPass directive specifies the mapping of incoming requests to the backend server (or a cluster of servers known as a Balancer group). The simpliest example proxies all requests ("/") to a single backend:

ProxyPass "/"  "http://www.example.com/"

To ensure that and Location: headers generated from the backend are modified to point to the reverse proxy, instead of back to itself, the ProxyPassReverse directive is most often required:

ProxyPass "/"  "http://www.example.com/"
ProxyPassReverse "/"  "http://www.example.com/"

Only specific URIs can be proxied, as shown in this example:

ProxyPass "/images"  "http://www.example.com/"
ProxyPassReverse "/images"  "http://www.example.com/"

In the above, any requests which start with the /images path with be proxied to the specified backend, otherwise it will be handled locally.

Clusters and Balancers

As useful as the above is, it still has the deficiencies that should the (single) backend node go down, or become heavily loaded, that proxying those requests provides no real advantage. What is needed is the ability to define a set or group of backend servers which can handle such requests and for the reverse proxy to load balance and failover among them. This group is sometimes called a cluster but Apache httpd's term is a balancer. One defines a balancer by leveraging the Proxy and BalancerMember directives as shown:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080
    ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

The balancer:// scheme is what tells httpd that we are creating a balancer set, with the name myset. It includes 2 backend servers, which httpd calls BalancerMembers. In this case, any requests for /images will be proxied to one of the 2 backends. The ProxySet directive specifies that the myset Balancer use a load balancing algorithm that balances based on I/O bytes.

Hint

BalancerMembers are also sometimes referred to as workers.

Balancer and BalancerMember configuration

You can adjust numerous configuration details of the balancers and the workers via the various parameters defined in ProxyPass. For example, assuming we would want http://www3.example.com:8080 to handle 3x the traffic with a timeout of 1 second, we would adjust the configuration as follows:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
    ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images"  "balancer://myset/"
ProxyPassReverse "/images"  "balancer://myset/"

Failover

You can also fine-tune various failover scenarios, detailing which workers and even which balancers should accessed in such cases. For example, the below setup implements 2 failover cases: In the first, http://hstandby.example.com:8080 is only sent traffic if all other workers in the myset balancer are not available. If that worker itself is not available, only then will the http://bkup1.example.com:8080 and http://bkup2.example.com:8080 workers be brought into rotation:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
    BalancerMember http://hstandby.example.com:8080 status=+H
    BalancerMember http://bkup1.example.com:8080 lbset=1
    BalancerMember http://bkup2.example.com:8080 lbset=1
    ProxySet lbmethod=byrequests
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

The magic of this failover setup is setting http://hstandby.example.com:8080 with the +H status flag, which puts it in hot standby mode, and making the 2 bkup# servers part of the #1 load balancer set (the default set is 0); for failover, hot standbys (if they exist) are used 1st, when all regular workers are unavailable; load balancer sets are always tried lowest number first.

Balancer Manager

One of the most unique and useful features of Apache httpd's reverse proxy is the embedded balancer-manager application. Similar to mod_status, balancer-manager displays the current working configuration and status of the enabled balancers and workers currently in use. However, not only does it display these parameters, it also allows for dynamic, runtime, on-the-fly reconfiguration of almost all of them, including adding new BalancerMembers (workers) to an existing balancer. To enable these capability, the following needs to be added to your configuration:

<Location "/balancer-manager">
    SetHandler balancer-manager
    Require host localhost
</Location>

Warning

Do not enable the balancer-manager until you have secured your server. In particular, ensure that access to the URL is tightly restricted.

When the reverse proxy server is accessed at that url (eg: http://rproxy.example.com/balancer-manager/, you will see a page similar to the below:

This form allows the devops admin to adjust various parameters, take workers offline, change load balancing methods and add new works. For example, clicking on the balancer itself, you will get the following page:

Whereas clicking on a worker, displays this page:

To have these changes persist restarts of the reverse proxy, ensure that BalancerPersist is enabled.

Dynamic Health Checks

Before httpd proxies a request to a worker, it can "test" if that worker is available via setting the ping parameter for that worker using ProxyPass. Oftentimes it is more useful to check the health of the workers out of band, in a dynamic fashion. This is achieved in Apache httpd by the mod_proxy_hcheck module.

BalancerMember status flags

In the balancer-manager the current state, or status, of a worker is displayed and can be set/reset. The meanings of these statuses are as follows:

Flag | String | Description
 | Ok | Worker is available
 | Init | Worker has been initialized
D | Dis | Worker is disabled and will not accept any requests; will be automatically retried.
S | Stop | Worker is administratively stopped; will not accept requests and will not be automatically retried
I | Ign | Worker is in ignore-errors mode and will always be considered available.
H | Stby | Worker is in hot-standby mode and will only be used if no other viable workers are available.
E | Err | Worker is in an error state, usually due to failing pre-request check; requests will not be proxied to this worker, but it will be retried depending on the retry setting of the worker.
N | Drn | Worker is in drain mode and will only accept existing sticky sessions destined for itself and ignore all other requests.
C | HcFl | Worker has failed dynamic health check and will not be used until it passes subsequent health checks.


Platform Specific Notes - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Platform Specific Notes

Microsoft Windows

Using Apache

This document explains how to install, configure and run Apache 2.4 under Microsoft Windows.

See: Using Apache with Microsoft Windows

Compiling Apache

There are many important points before you begin compiling Apache. This document explain them.

See: Compiling Apache for Microsoft Windows

Unix Systems

RPM Based Systems (Redhat / CentOS / Fedora)

This document explains how to build, install, and run Apache 2.4 on systems supporting the RPM packaging format.

See: Using Apache With RPM Based Systems

Other Platforms

Novell NetWare

This document explains how to install, configure and run Apache 2.4 under Novell NetWare 5.1 and above.

See: Using Apache With Novell NetWare

EBCDIC

Version 1.3 of the Apache HTTP Server is the first version which includes a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

Warning: This document has not been updated to take into account changes made in the 2.4 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

See: The Apache EBCDIC Port

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using Apache HTTP Server on Microsoft Windows - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Using Apache HTTP Server on Microsoft Windows

This document explains how to install, configure and run Apache 2.4 under Microsoft Windows. If you have questions after reviewing the documentation (and any event and error logs), you should consult the peer-supported users' mailing list.

This document assumes that you are installing a binary distribution of Apache. If you want to compile Apache yourself (possibly to help with development or tracking down bugs), see Compiling Apache for Microsoft Windows.

Operating System Requirements

The primary Windows platform for running Apache 2.4 is Windows 2000 or later. Always obtain and install the current service pack to avoid operating system bugs.

Apache HTTP Server versions later than 2.2 will not run on any operating system earlier than Windows 2000.

Downloading Apache for Windows

The Apache HTTP Server Project itself does not provide binary releases of software, only source code. Individual committers may provide binary packages as a convenience, but it is not a release deliverable.

If you cannot compile the Apache HTTP Server yourself, you can obtain a binary package from numerous binary distributions available on the Internet.

Popular options for deploying Apache httpd, and, optionally, PHP and MySQL, on Microsoft Windows, include:

  • ApacheHaus
  • Apache Lounge
  • BitNami WAMP Stack
  • WampServer
  • XAMPP

Customizing Apache for Windows

Apache is configured by the files in the conf subdirectory. These are the same files used to configure the Unix version, but there are a few different directives for Apache on Windows. See the directive index for all the available directives.

The main differences in Apache for Windows are:

  • Because Apache for Windows is multithreaded, it does not use a separate process for each request, as Apache can on Unix. Instead there are usually only two Apache processes running: a parent process, and a child which handles the requests. Within the child process each request is handled by a separate thread.

    The process management directives are also different:

    MaxConnectionsPerChild: Like the Unix directive, this controls how many connections a single child process will serve before exiting. However, unlike on Unix, a replacement process is not instantly available. Use the default MaxConnectionsPerChild 0, unless instructed to change the behavior to overcome a memory leak in third party modules or in-process applications.

    Warning: The server configuration file is reread when a new child process is started. If you have modified httpd.conf, the new child may not start or you may receive unexpected results.

    ThreadsPerChild: This directive is new. It tells the server how many threads it should use. This is the maximum number of connections the server can handle at once, so be sure to set this number high enough for your site if you get a lot of hits. The recommended default is ThreadsPerChild 150, but this must be adjusted to reflect the greatest anticipated number of simultaneous connections to accept.

  • The directives that accept filenames as arguments must use Windows filenames instead of Unix ones. However, because Apache may interpret backslashes as an "escape character" sequence, you should consistently use forward slashes in path names, not backslashes.

  • While filenames are generally case-insensitive on Windows, URLs are still treated internally as case-sensitive before they are mapped to the filesystem. For example, the <Location>, Alias, and ProxyPass directives all use case-sensitive arguments. For this reason, it is particularly important to use the <Directory> directive when attempting to limit access to content in the filesystem, since this directive applies to any content in a directory, regardless of how it is accessed. If you wish to assure that only lowercase is used in URLs, you can use something like:

    RewriteEngine On
RewriteMap lowercase int:tolower
RewriteCond "%{REQUEST_URI}" "[A-Z]"
RewriteRule "(.*)" "${lowercase:$1}" [R,L]

  • When running, Apache needs write access only to the logs directory and any configured cache directory tree. Due to the issue of case insensitive and short 8.3 format names, Apache must validate all path names given. This means that each directory which Apache evaluates, from the drive root up to the directory leaf, must have read, list and traverse directory permissions. If Apache2.4 is installed at C:\Program Files, then the root directory, Program Files and Apache2.4 must all be visible to Apache.

  • Apache for Windows contains the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2.4\modules directory. To activate these or other modules, the LoadModule directive must be used. For example, to activate the status module, use the following (in addition to the status-activating directives in access.conf):

    LoadModule status_module modules/mod_status.so

    Information on creating loadable modules is also available.

  • Apache can also load ISAPI (Internet Server Application Programming Interface) extensions such as those used by Microsoft IIS and other Windows servers. More information is available. Note that Apache cannot load ISAPI Filters, and ISAPI Handlers with some Microsoft feature extensions will not work.

  • When running CGI scripts, the method Apache uses to find the interpreter for the script is configurable using the ScriptInterpreterSource directive.

  • Since it is often difficult to manage files with names like .htaccess in Windows, you may find it useful to change the name of this per-directory configuration file using the AccessFilename directive.

  • Any errors during Apache startup are logged into the Windows event log when running on Windows NT. This mechanism acts as a backup for those situations where Apache is not yet prepared to use the error.log file. You can review the Windows Application Event Log by using the Event Viewer, e.g. Start - Settings - Control Panel - Administrative Tools - Event Viewer.

Running Apache as a Service

Apache comes with a utility called the Apache Service Monitor. With it you can see and manage the state of all installed Apache services on any machine on your network. To be able to manage an Apache service with the monitor, you have to first install the service (either automatically via the installation or manually).

You can install Apache as a Windows NT service as follows from the command prompt at the Apache bin subdirectory:

httpd.exe -k install

If you need to specify the name of the service you want to install, use the following command. You have to do this if you have several different service installations of Apache on your computer. If you specify a name during the install, you have to also specify it during any other -k operation.

httpd.exe -k install -n "MyServiceName"

If you need to have specifically named configuration files for different services, you must use this:

httpd.exe -k install -n "MyServiceName" -f "c:\files\my.conf"

If you use the first command without any special parameters except -k install, the service will be called Apache2.4 and the configuration will be assumed to be conf\httpd.conf.

Removing an Apache service is easy. Just use:

httpd.exe -k uninstall

The specific Apache service to be uninstalled can be specified by using:

httpd.exe -k uninstall -n "MyServiceName"

Normal starting, restarting and shutting down of an Apache service is usually done via the Apache Service Monitor, by using commands like NET START Apache2.4 and NET STOP Apache2.4 or via normal Windows service management. Before starting Apache as a service by any means, you should test the service's configuration file by using:

httpd.exe -n "MyServiceName" -t

You can control an Apache service by its command line switches, too. To start an installed Apache service you'll use this:

httpd.exe -k start -n "MyServiceName"

To stop an Apache service via the command line switches, use this:

httpd.exe -k stop -n "MyServiceName"

or

httpd.exe -k shutdown -n "MyServiceName"

You can also restart a running service and force it to reread its configuration file by using:

httpd.exe -k restart -n "MyServiceName"

By default, all Apache services are registered to run as the system user (the LocalSystem account). The LocalSystem account has no privileges to your network via any Windows-secured mechanism, including the file system, named pipes, DCOM, or secure RPC. It has, however, wide privileges locally.

Never grant any network privileges to the LocalSystem account! If you need Apache to be able to access network resources, create a separate account for Apache as noted below.

It is recommended that users create a separate account for running Apache service(s). If you have to access network resources via Apache, this is required.

  1. Create a normal domain user account, and be sure to memorize its password.
  2. Grant the newly-created user a privilege of Log on as a service and Act as part of the operating system. On Windows NT 4.0 these privileges are granted via User Manager for Domains, but on Windows 2000 and XP you probably want to use Group Policy for propagating these settings. You can also manually set these via the Local Security Policy MMC snap-in.
  3. Confirm that the created account is a member of the Users group.
  4. Grant the account read and execute (RX) rights to all document and script folders (htdocs and cgi-bin for example).
  5. Grant the account change (RWXD) rights to the Apache logs directory.
  6. Grant the account read and execute (RX) rights to the httpd.exe binary executable.
It is usually a good practice to grant the user the Apache service runs as read and execute (RX) access to the whole Apache2.4 directory, except the logs subdirectory, where the user has to have at least change (RWXD) rights.

If you allow the account to log in as a user and as a service, then you can log on with that account and test that the account has the privileges to execute the scripts, read the web pages, and that you can start Apache in a console window. If this works, and you have followed the steps above, Apache should execute as a service with no problems.

Error code 2186 is a good indication that you need to review the "Log On As" configuration for the service, since Apache cannot access a required network resource. Also, pay close attention to the privileges of the user Apache is configured to run as.

When starting Apache as a service you may encounter an error message from the Windows Service Control Manager. For example, if you try to start Apache by using the Services applet in the Windows Control Panel, you may get the following message:

Could not start the Apache2.4 service on \\COMPUTER
Error 1067; The process terminated unexpectedly.

You will get this generic error if there is any problem with starting the Apache service. In order to see what is really causing the problem you should follow the instructions for Running Apache for Windows from the Command Prompt.

If you are having problems with the service, it is suggested you follow the instructions below to try starting httpd.exe from a console window, and work out the errors before struggling to start it as a service again.

Running Apache as a Console Application

Running Apache as a service is usually the recommended way to use it, but it is sometimes easier to work from the command line, especially during initial configuration and testing.

To run Apache from the command line as a console application, use the following command:

httpd.exe

Apache will execute, and will remain running until it is stopped by pressing Control-C.

You can also run Apache via the shortcut Start Apache in Console placed to Start Menu --> Programs --> Apache HTTP Server 2.4.xx --> Control Apache Server during the installation. This will open a console window and start Apache inside it. If you don't have Apache installed as a service, the window will remain visible until you stop Apache by pressing Control-C in the console window where Apache is running in. The server will exit in a few seconds. However, if you do have Apache installed as a service, the shortcut starts the service. If the Apache service is running already, the shortcut doesn't do anything.

If Apache is running as a service, you can tell it to stop by opening another console window and entering:

httpd.exe -k shutdown

Running as a service should be preferred over running in a console window because this lets Apache end any current operations and clean up gracefully.

But if the server is running in a console window, you can only stop it by pressing Control-C in the same window.

You can also tell Apache to restart. This forces it to reread the configuration file. Any operations in progress are allowed to complete without interruption. To restart Apache, either press Control-Break in the console window you used for starting Apache, or enter

httpd.exe -k restart

if the server is running as a service.

Note for people familiar with the Unix version of Apache: these commands provide a Windows equivalent to kill -TERM pid and kill -USR1 pid. The command line option used, -k, was chosen as a reminder of the kill command used on Unix.

If the Apache console window closes immediately or unexpectedly after startup, open the Command Prompt from the Start Menu --> Programs. Change to the folder to which you installed Apache, type the command httpd.exe, and read the error message. Then change to the logs folder, and review the error.log file for configuration mistakes. Assuming httpd was installed into C:\Program Files\Apache Software Foundation\Apache2.4\, you can do the following:

c:
cd "\Program Files\Apache Software Foundation\Apache2.4\bin"
httpd.exe

Then wait for Apache to stop, or press Control-C. Then enter the following:

cd ..\logs
more < error.log

When working with Apache it is important to know how it will find the configuration file. You can specify a configuration file on the command line in two ways:

  • -f specifies an absolute or relative path to a particular configuration file:

    httpd.exe -f "c:\my server files\anotherconfig.conf"

    or

    httpd.exe -f files\anotherconfig.conf

  • -n specifies the installed Apache service whose configuration file is to be used:

    httpd.exe -n "MyServiceName"

In both of these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file with -f or -n, Apache will use the file name compiled into the server, such as conf\httpd.conf. This built-in path is relative to the installation directory. You can verify the compiled file name from a value labelled as SERVER_CONFIG_FILE when invoking Apache with the -V switch, like this:

httpd.exe -V

Apache will then try to determine its ServerRoot by trying the following, in this order:

  1. A ServerRoot directive via the -C command line switch.
  2. The -d switch on the command line.
  3. Current working directory.
  4. A registry entry which was created if you did a binary installation.
  5. The server root compiled into the server. This is /apache by default, you can verify it by using httpd.exe -V and looking for a value labelled as HTTPD_ROOT.

If you did not do a binary install, Apache will in some scenarios complain about the missing registry key. This warning can be ignored if the server was otherwise able to find its configuration file.

The value of this key is the ServerRoot directory which contains the conf subdirectory. When Apache starts it reads the httpd.conf file from that directory. If this file contains a ServerRoot directive which contains a different directory from the one obtained from the registry key above, Apache will forget the registry key and use the directory from the configuration file. If you copy the Apache directory or configuration files to a new location it is vital that you update the ServerRoot directive in the httpd.conf file to reflect the new location.

Testing the Installation

After starting Apache (either in a console window or as a service) it will be listening on port 80 (unless you changed the Listen directive in the configuration files or installed Apache only for the current user). To connect to the server and access the default page, launch a browser and enter this URL:

http://localhost/

Apache should respond with a welcome page and you should see "It Works!". If nothing happens or you get an error, look in the error.log file in the logs subdirectory. If your host is not connected to the net, or if you have serious problems with your DNS (Domain Name Service) configuration, you may have to use this URL:

http://127.0.0.1/

If you happen to be running Apache on an alternate port, you need to explicitly put that in the URL:

http://127.0.0.1:8080/

Once your basic installation is working, you should configure it properly by editing the files in the conf subdirectory. Again, if you change the configuration of the Windows NT service for Apache, first attempt to start it from the command line to make sure that the service starts with no errors.

Because Apache cannot share the same port with another TCP/IP application, you may need to stop, uninstall or reconfigure certain other services before running Apache. These conflicting services include other WWW servers, some firewall implementations, and even some client applications (such as Skype) which will use port 80 to attempt to bypass firewall issues.

Configuring Access to Network Resources

Access to files over the network can be specified using two mechanisms provided by Windows:

Mapped drive letters
e.g., Alias "/images/" "Z:/"
UNC paths
e.g., Alias "/images/" "//imagehost/www/images/"

Mapped drive letters allow the administrator to maintain the mapping to a specific machine and path outside of the Apache httpd configuration. However, these mappings are associated only with interactive sessions and are not directly available to Apache httpd when it is started as a service. Use only UNC paths for network resources in httpd.conf so that the resources can be accessed consistently regardless of how Apache httpd is started. (Arcane and error prone procedures may work around the restriction on mapped drive letters, but this is not recommended.)

Example DocumentRoot with UNC path

DocumentRoot "//dochost/www/html/"

Example DocumentRoot with IP address in UNC path

DocumentRoot "//192.168.1.50/docs/"

Example Alias and corresponding Directory with UNC path

Alias "/images/" "//imagehost/www/images/"

<Directory "//imagehost/www/images/">
#...
<Directory>

When running Apache httpd as a service, you must create a separate account in order to access network resources, as described above.

Windows Tuning

  • If more than a few dozen piped loggers are used on an operating system instance, scaling up the "desktop heap" is often necessary. For more detailed information, refer to the piped logging documentation.


Compiling Apache for Microsoft Windows - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Compiling Apache for Microsoft Windows

There are many important points to consider before you begin compiling Apache HTTP Server (httpd). See Using Apache HTTP Server on Microsoft Windows before you begin.

httpd can be built on Windows using a cmake-based build system or with Visual Studio project files maintained by httpd developers. The cmake-based build system directly supports more versions of Visual Studio but currently has considerable functional limitations.

Building httpd with the included Visual Studio project files

Requirements

Compiling Apache requires the following environment to be properly installed:

  • Disk Space

    Make sure you have at least 200 MB of free disk space available. After installation Apache requires approximately 80 MB of disk space, plus space for log and cache files, which can grow rapidly. The actual disk space requirements will vary considerably based on your chosen configuration and any third-party modules or libraries, especially when OpenSSL is also built. Because many files are text and very easily compressed, NTFS filesystem compression cuts these requirements in half.

  • Appropriate Patches

    The httpd binary is built with the help of several patches to third party packages, which ensure the released code is buildable and debuggable. These patches are available and distributed from http://www.apache.org/dist/httpd/binaries/win32/patches_applied/ and are recommended to be applied to obtain identical results as the "official" ASF distributed binaries.

  • Microsoft Visual C++ 6.0 (Visual Studio 97) or later.

    Apache can be built using the command line tools, or from within the Visual Studio IDE Workbench. The command line build requires the environment to reflect the PATH, INCLUDE, LIB and other variables that can be configured with the vcvars32.bat script.

    You may want the Visual Studio Processor Pack for your older version of Visual Studio, or a full (not Express) version of newer Visual Studio editions, for the ml.exe assembler. This will allow you to build OpenSSL, if desired, using the more efficient assembly code implementation.
    Only the Microsoft compiler tool chain is actively supported by the active httpd contributors. Although the project regularly accepts patches to ensure MinGW and other alternative builds work and improve upon them, they are not actively maintained and are often broken in the course of normal development.

  • Updated Microsoft Windows Platform SDK, February 2003 or later.

    An appropriate Windows Platform SDK is included by default in the full (not express/lite) versions of Visual C++ 7.1 (Visual Studio 2002) and later, these users can ignore these steps unless explicitly choosing a newer or different version of the Platform SDK.

    To use Visual C++ 6.0 or 7.0 (Studio 2000 .NET), the Platform SDK environment must be prepared using the setenv.bat script (installed by the Platform SDK) before starting the command line build or launching the msdev/devenv GUI environment. Installing the Platform SDK for Visual Studio Express versions (2003 and later) should adjust the default environment appropriately.

    "c:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32"
    "c:\Program Files\Platform SDK\setenv.bat"

  • Perl and awk

    Several steps recommended here require a perl interpreter during the build preparation process, but it is otherwise not required.

    To install Apache within the build system, several files are modified using the awk.exe utility. awk was chosen since it is a very small download (compared with Perl or WSH/VB) and accomplishes the task of modifying configuration files upon installation. Brian Kernighan's http://www.cs.princeton.edu/~bwk/btl.mirror/ site has a compiled native Win32 binary, http://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe which you must save with the name awk.exe (rather than awk95.exe).

    If awk.exe is not found, Makefile.win's install target will not perform substitutions in the installed .conf files. You must manually modify the installed .conf files to allow the server to start. Search and replace all "@token@" tags as appropriate.
    The Visual Studio IDE will only find awk.exe from the PATH, or executable path specified in the menu option Tools -> Options -> (Projects ->) Directories. Ensure awk.exe is in your system path.
    Also note that if you are using Cygwin tools (http://www.cygwin.com/) the awk utility is named gawk.exe and that the file awk.exe is really a symlink to the gawk.exe file. The Windows command shell does not recognize symlinks, and because of this building InstallBin will fail. A workaround is to delete awk.exe from the cygwin installation and copy gawk.exe to awk.exe. Also note the cygwin/mingw ports of gawk 3.0.x were buggy, please upgrade to 3.1.x before attempting to use any gawk port.

  • [Optional] zlib library (for mod_deflate)

    Zlib must be installed into a srclib subdirectory named zlib. This must be built in-place. Zlib can be obtained from http://www.zlib.net/ -- the mod_deflate is confirmed to work correctly with version 1.2.3.

    nmake -f win32\Makefile.msc
    nmake -f win32\Makefile.msc test

  • [Optional] OpenSSL libraries (for mod_ssl and ab.exe with ssl support)

    The OpenSSL library is cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

    Configuring and building OpenSSL requires perl to be installed.

    OpenSSL must be installed into a srclib subdirectory named openssl, obtained from http://www.openssl.org/source/, in order to compile mod_ssl or the abs.exe project, which is ab.c with SSL support enabled. To prepare OpenSSL to be linked to Apache mod_ssl or abs.exe, and disable patent encumbered features in OpenSSL, you might use the following build commands:

    perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32 -Ipath/to/srclib/zlib -Lpath/to/srclib/zlib
    ms\do_masm.bat
    nmake -f ms\ntdll.mak

    It is not advisable to use zlib-dynamic, as that transfers the cost of deflating SSL streams to the first request which must load the zlib dll. Note the suggested patch enables the -L flag to work with windows builds, corrects the name of zdll.lib and ensures .pdb files are generated for troubleshooting. If the assembler is not installed, you would add no-asm above and use ms\do_ms.bat instead of the ms\do_masm.bat script.

  • [Optional] Database libraries (for mod_dbd and mod_authn_dbm)

    The apr-util library exposes dbm (keyed database) and dbd (query oriented database) client functionality to the httpd server and its modules, such as authentication and authorization. The sdbm dbm and odbc dbd providers are compiled unconditionally.

    The dbd support includes the Oracle instantclient package, MySQL, PostgreSQL and sqlite. To build these all, for example, set up the LIB to include the library path, INCLUDE to include the headers path, and PATH to include the dll bin path of all four SDK's, and set the DBD_LIST environment variable to inform the build which client driver SDKs are installed correctly, e.g.;

    set DBD_LIST=sqlite3 pgsql oracle mysql

    Similarly, the dbm support can be extended with DBM_LIST to build a Berkeley DB provider (db) and/or gdbm provider, by similarly configuring LIB, INCLUDE and PATH first to ensure the client library libs and headers are available.

    set DBM_LIST=db gdbm

    Depending on the choice of database distributions, it may be necessary to change the actual link target name (e.g. gdbm.lib vs. libgdb.lib) that are listed in the corresponding .dsp/.mak files within the directories srclib\apr-util\dbd or ...\dbm.

    See the README-win32.txt file for more hints on obtaining the various database driver SDKs.

Building from Unix sources

The policy of the Apache HTTP Server project is to only release Unix sources. Windows source packages made available for download have been supplied by volunteers and may not be available for every release. You can still build the server on Windows from the Unix source tarball with just a few additional steps.

  1. Download and unpack the Unix source tarball for the latest version.
  2. Download and unpack the Unix source tarball for latest version of APR, AR-Util and APR-Iconv, place these sources in directories httpd-2.x.x\srclib\apr, httpd-2.x.x\srclib\apr-util and httpd-2.x.x\srclib\apr-iconv
  3. Open a Command Prompt and CD to the httpd-2.x.x folder
  4. Run the line endings conversion utility at the prompt;

perl srclib\apr\build\lineends.pl

You can now build the server with the Visual Studio development environment using the IDE. Command-Line builds of the server are not possible from Unix sources unless you export .mak files as explained below.

Command-Line Build

Makefile.win is the top level Apache makefile. To compile Apache on Windows, simply use one of the following commands to build the release or debug flavor:

nmake /f Makefile.win _apacher

nmake /f Makefile.win _apached

Either command will compile Apache. The latter will disable optimization of the resulting files, making it easier to single step the code to find bugs and track down problems.

You can add your apr-util dbd and dbm provider choices with the additional make (environment) variables DBD_LIST and DBM_LIST, see the comments about [Optional] Database libraries, above. Review the initial comments in Makefile.win for additional options that can be provided when invoking the build.

Developer Studio Workspace IDE Build

Apache can also be compiled using VC++'s Visual Studio development environment. To simplify this process, a Visual Studio workspace, Apache.dsw, is provided. This workspace exposes the entire list of working .dsp projects that are required for the complete Apache binary release. It includes dependencies between the projects to assure that they are built in the appropriate order.

Open the Apache.dsw workspace, and select InstallBin (Release or Debug build, as desired) as the Active Project. InstallBin causes all related project to be built, and then invokes Makefile.win to move the compiled executables and dlls. You may personalize the INSTDIR= choice by changing InstallBin's Settings, General tab, Build command line entry. INSTDIR defaults to the /Apache2 directory. If you only want a test compile (without installing) you may build the BuildBin project instead.

The .dsp project files are distributed in Visual Studio 6.0 (98) format. Visual C++ 5.0 (97) will recognize them. Visual Studio 2002 (.NET) and later users must convert Apache.dsw plus the .dsp files into an Apache.sln plus .msproj files. Be sure you reconvert the .msproj file again if its source .dsp file changes! This is really trivial, just open Apache.dsw in the VC++ 7.0 IDE once again and reconvert.

There is a flaw in the .vcproj conversion of .dsp files. devenv.exe will mis-parse the /D flag for RC flags containing long quoted /D'efines which contain spaces. The command:

perl srclib\apr\build\cvtdsp.pl -2005

will convert the /D flags for RC flags to use an alternate, parseable syntax; unfortunately this syntax isn't supported by Visual Studio 97 or its exported .mak files. These /D flags are used to pass the long description of the mod_apachemodule.so files to the shared .rc resource version-identifier build.

Visual Studio 2002 (.NET) and later users should also use the Build menu, Configuration Manager dialog to uncheck both the Debug and Release Solution modules abs, mod_deflate and mod_ssl components, as well as every component starting with apr_db*. These modules are built by invoking nmake, or the IDE directly with the BinBuild target, which builds those modules conditionally if the srclib directories openssl and/or zlib exist, and based on the setting of DBD_LIST and DBM_LIST environment variables.

Exporting command-line .mak files

Exported .mak files pose a greater hassle, but they are required for Visual C++ 5.0 users to build mod_ssl, abs (ab with SSL support) and/or mod_deflate. The .mak files also support a broader range of C++ tool chain distributions, such as Visual Studio Express.

You must first build all projects in order to create all dynamic auto-generated targets, so that dependencies can be parsed correctly. Build the entire project from within the Visual Studio 6.0 (98) IDE, using the BuildAll target, then use the Project Menu Export for all makefiles (checking on "with dependencies".) Run the following command to correct absolute paths into relative paths so they will build anywhere:

perl srclib\apr\build\fixwin32mak.pl

You must type this command from the top level directory of the httpd source tree. Every .mak and .dep project file within the current directory and below will be corrected, and the timestamps adjusted to reflect the .dsp.

Always review the generated .mak and .dep files for Platform SDK or other local, machine specific file paths. The DevStudio\Common\MSDev98\bin\ (VC6) directory contains a sysincl.dat file, which lists all exceptions. Update this file (including both forward and backslashed paths, such as both sys/time.h and sys\time.h) to ignore such newer dependencies. Including local-install paths in a distributed .mak file will cause the build to fail completely.

If you contribute back a patch that revises project files, we must commit project files in Visual Studio 6.0 format. Changes should be simple, with minimal compilation and linkage flags that can be recognized by all Visual Studio environments.

Installation

Once Apache has been compiled, it needs to be installed in its server root directory. The default is the \Apache2 directory, of the same drive.

To build and install all the files into the desired folder dir automatically, use one of the following nmake commands:

nmake /f Makefile.win installr INSTDIR=dir
nmake /f Makefile.win installd INSTDIR=dir

The dir argument to INSTDIR provides the installation directory; it can be omitted if Apache is to be installed into \Apache22 (of the current drive).

Warning about building Apache from the development tree

Note only the .dsp files are maintained between release builds. The .mak files are NOT regenerated, due to the tremendous waste of reviewer's time. Therefore, you cannot rely on the NMAKE commands above to build revised .dsp project files unless you then export all .mak files yourself from the project. This is unnecessary if you build from within the Microsoft Developer Studio environment.

Building httpd with cmake

The primary documentation for this build mechanism is in the README.cmake file in the source distribution. Refer to that file for detailed instructions.

Building httpd with cmake requires building APR and APR-util separately. Refer to their README.cmake files for instructions.

The primary limitations of the cmake-based build are inherited from the APR-util project, and are listed below because of their impact on httpd:

  • No cmake build for the APR-iconv subproject is available, and the APR-util cmake build cannot consume an existing APR-iconv build. Thus, mod_charset_lite and possibly some third-party modules cannot be used.
  • The cmake build for the APR-util subproject does not support most of the optional DBM and DBD libraries supported by the included Visual Studio project files. This limits the database backends supported by a number of bundled and third-party modules.


Using Apache With RPM Based Systems (Redhat / CentOS / Fedora) - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Using Apache With RPM Based Systems (Redhat / CentOS / Fedora)

While many distributions make Apache httpd available as operating system supported packages, it can sometimes be desirable to install and use the canonical version of Apache httpd on these systems, replacing the natively provided versions of the packages.

While the Apache httpd project does not currently create binary RPMs for the various distributions out there, it is easy to build your own binary RPMs from the canonical Apache httpd tarball.

This document explains how to build, install, configure and run Apache httpd 2.4 under Unix systems supporting the RPM packaging format.

Creating a Source RPM

The Apache httpd source tarball can be converted into an SRPM as follows:

rpmbuild -ts httpd-2.4.x.tar.bz2

Building RPMs

RPMs can be built directly from the Apache httpd source tarballs using the following command:

rpmbuild -tb httpd-2.4.x.tar.bz2

Corresponding "-devel" packages will be required to be installed on your build system prior to building the RPMs, the rpmbuild command will automatically calculate what RPMs are required and will list any dependencies that are missing on your system. These "-devel" packages will not be required after the build is completed, and can be safely removed.

If successful, the following RPMs will be created:

httpd-2.4.x-1.i686.rpm
The core server and basic module set.
httpd-debuginfo-2.4.x-1.i686.rpm
Debugging symbols for the server and all modules.
httpd-devel-2.4.x-1.i686.rpm
Headers and development files for the server.
httpd-manual-2.4.x-1.i686.rpm
The webserver manual.
httpd-tools-2.4.x-1.i686.rpm
Supporting tools for the webserver.
mod_authnz_ldap-2.4.x-1.i686.rpm
mod_ldap and mod_authnz_ldap, with corresponding dependency on openldap.
mod_lua-2.4.x-1.i686.rpm
mod_lua module, with corresponding dependency on lua.
mod_proxy_html-2.4.x-1.i686.rpm
mod_proxy_html module, with corresponding dependency on libxml2.
mod_socache_dc-2.4.x-1.i686.rpm
mod_socache_dc module, with corresponding dependency on distcache.
mod_ssl-2.4.x-1.i686.rpm
mod_ssl module, with corresponding dependency on openssl.

Installing the Server

The httpd RPM is the only RPM necessary to get a basic server to run. Install it as follows:

rpm -U httpd-2.4.x-1.i686.rpm

Self contained modules are included with the server. Modules that depend on external libraries are provided as separate RPMs to install if needed.

Configuring the Default Instance of Apache httpd

The default configuration for the server is installed by default beneath the /etc/httpd directory, with logs written by default to /var/log/httpd. The environment for the webserver is set by default within the optional /etc/sysconfig/httpd file.

Start the server as follows:

service httpd restart

Configuring Additional Instances of Apache httpd on the Same Machine

It is possible to configure additional instances of the Apache httpd server running independently alongside each other on the same machine. These instances can have independent configurations, and can potentially run as separate users if so configured.

This was done by making the httpd startup script aware of its own name. This name is then used to find the environment file for the server, and in turn, the server root of the server instance.

To create an additional instance called httpd-additional, follow these steps:

  • Create a symbolic link to the startup script for the additional server:

    ln -s /etc/rc.d/init.d/httpd /etc/rc.d/init.d/httpd-additional
    chkconfig --add httpd-additional

  • Create an environment file for the server, using the /etc/sysconfig/httpd file as a template:

    # template from httpd
    cp /etc/sysconfig/httpd /etc/sysconfig/httpd-additional

    # blank template
    touch /etc/sysconfig/httpd-additional

    Edit /etc/sysconfig/httpd-additional and pass the server root of the new server instance within the OPTIONS environment variable.

    OPTIONS="-d /etc/httpd-additional -f conf/httpd-additional.conf"

  • Edit the server configuration file /etc/httpd-additional/conf/httpd-additional.conf to ensure the correct ports and paths are configured.
  • Start the server as follows:

    service httpd-additional restart

  • Repeat this process as required for each server instance.


Using Apache With Novell NetWare - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Using Apache With Novell NetWare

This document explains how to install, configure and run Apache 2.0 under Novell NetWare 6.0 and above. If you find any bugs, or wish to contribute in other ways, please use our bug reporting page.

The bug reporting page and dev-httpd mailing list are not provided to answer questions about configuration or running Apache. Before you submit a bug report or request, first consult this document, the Frequently Asked Questions page and the other relevant documentation topics. If you still have a question or problem, post it to the novell.devsup.webserver newsgroup, where many Apache users are more than willing to answer new and obscure questions about using Apache on NetWare.

Most of this document assumes that you are installing Apache from a binary distribution. If you want to compile Apache yourself (possibly to help with development, or to track down bugs), see the section on Compiling Apache for NetWare below.

Requirements

Apache 2.0 is designed to run on NetWare 6.0 service pack 3 and above. If you are running a service pack less than SP3, you must install the latest NetWare Libraries for C (LibC).

NetWare service packs are available here.

Apache 2.0 for NetWare can also be run in a NetWare 5.1 environment as long as the latest service pack or the latest version of the NetWare Libraries for C (LibC) has been installed . WARNING: Apache 2.0 for NetWare has not been targeted for or tested in this environment.

Downloading Apache for NetWare

Information on the latest version of Apache can be found on the Apache web server at http://www.apache.org/. This will list the current release, any more recent alpha or beta-test releases, together with details of mirror web and anonymous ftp sites. Binary builds of the latest releases of Apache 2.0 for NetWare can be downloaded from here.

Installing Apache for NetWare

There is no Apache install program for NetWare currently. If you are building Apache 2.0 for NetWare from source, you will need to copy the files over to the server manually.

Follow these steps to install Apache on NetWare from the binary download (assuming you will install to sys:/apache2):

  • Unzip the binary download file to the root of the SYS: volume (may be installed to any volume)
  • Edit the httpd.conf file setting ServerRoot and ServerName along with any file path values to reflect your correct server settings
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Follow these steps to install Apache on NetWare manually from your own build source (assuming you will install to sys:/apache2):

  • Create a directory called Apache2 on a NetWare volume
  • Copy APACHE2.NLM, APRLIB.NLM to SYS:/APACHE2
  • Create a directory under SYS:/APACHE2 called BIN
  • Copy HTDIGEST.NLM, HTPASSWD.NLM, HTDBM.NLM, LOGRES.NLM, ROTLOGS.NLM to SYS:/APACHE2/BIN
  • Create a directory under SYS:/APACHE2 called CONF
  • Copy the HTTPD-STD.CONF file to the SYS:/APACHE2/CONF directory and rename to HTTPD.CONF
  • Copy the MIME.TYPES, CHARSET.CONV and MAGIC files to SYS:/APACHE2/CONF directory
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ICONS to SYS:/APACHE2/ICONS
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\MANUAL to SYS:/APACHE2/MANUAL
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ERROR to SYS:/APACHE2/ERROR
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\DOCROOT to SYS:/APACHE2/HTDOCS
  • Create the directory SYS:/APACHE2/LOGS on the server
  • Create the directory SYS:/APACHE2/CGI-BIN on the server
  • Create the directory SYS:/APACHE2/MODULES and copy all nlm modules into the modules directory
  • Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Apache may be installed to other volumes besides the default SYS volume.

During the build process, adding the keyword "install" to the makefile command line will automatically produce a complete distribution package under the subdirectory DIST. Install Apache by simply copying the distribution that was produced by the makfiles to the root of a NetWare volume (see: Compiling Apache for NetWare below).

Running Apache for NetWare

To start Apache just type apache at the console. This will load apache in the OS address space. If you prefer to load Apache in a protected address space you may specify the address space with the load statement as follows:

load address space = apache2 apache2

This will load Apache into an address space called apache2. Running multiple instances of Apache concurrently on NetWare is possible by loading each instance into its own protected address space.

After starting Apache, it will be listening to port 80 (unless you changed the Listen directive in the configuration files). To connect to the server and access the default page, launch a browser and enter the server's name or address. This should respond with a welcome page, and a link to the Apache manual. If nothing happens or you get an error, look in the error_log file in the logs directory.

Once your basic installation is working, you should configure it properly by editing the files in the conf directory.

To unload Apache running in the OS address space just type the following at the console:

unload apache2

or

apache2 shutdown

If apache is running in a protected address space specify the address space in the unload statement:

unload address space = apache2 apache2

When working with Apache it is important to know how it will find the configuration files. You can specify a configuration file on the command line in two ways:

  • -f specifies a path to a particular configuration file

apache2 -f "vol:/my server/conf/my.conf"

apache -f test/test.conf

In these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file name with -f, Apache will use the file name compiled into the server, usually conf/httpd.conf. Invoking Apache with the -V switch will display this value labeled as SERVER_CONFIG_FILE. Apache will then determine its ServerRoot by trying the following, in this order:

  • A ServerRoot directive via a -C switch.
  • The -d switch on the command line.
  • Current working directory
  • The server root compiled into the server.

The server root compiled into the server is usually sys:/apache2. invoking apache with the -V switch will display this value labeled as HTTPD_ROOT.

Apache 2.0 for NetWare includes a set of command line directives that can be used to modify or display information about the running instance of the web server. These directives are only available while Apache is running. Each of these directives must be preceded by the keyword APACHE2.

RESTART
Instructs Apache to terminate all running worker threads as they become idle, reread the configuration file and restart each worker thread based on the new configuration.
VERSION
Displays version information about the currently running instance of Apache.
MODULES
Displays a list of loaded modules both built-in and external.
DIRECTIVES
Displays a list of all available directives.
SETTINGS
Enables or disables the thread status display on the console. When enabled, the state of each running threads is displayed on the Apache console screen.
SHUTDOWN
Terminates the running instance of the Apache web server.
HELP
Describes each of the runtime directives.

By default these directives are issued against the instance of Apache running in the OS address space. To issue a directive against a specific instance running in a protected address space, include the -p parameter along with the name of the address space. For more information type "apache2 Help" on the command line.

Configuring Apache for NetWare

Apache is configured by reading configuration files usually stored in the conf directory. These are the same as files used to configure the Unix version, but there are a few different directives for Apache on NetWare. See the Apache module documentation for all the available directives.

The main differences in Apache for NetWare are:

  • Because Apache for NetWare is multithreaded, it does not use a separate process for each request, as Apache does on some Unix implementations. Instead there are only threads running: a parent thread, and multiple child or worker threads which handle the requests.

    Therefore the "process"-management directives are different:

    MaxConnectionsPerChild - Like the Unix directive, this controls how many connections a worker thread will serve before exiting. The recommended default, MaxConnectionsPerChild 0, causes the thread to continue servicing request indefinitely. It is recommended on NetWare, unless there is some specific reason, that this directive always remain set to 0.

    StartThreads - This directive tells the server how many threads it should start initially. The recommended default is StartThreads 50.

    MinSpareThreads - This directive instructs the server to spawn additional worker threads if the number of idle threads ever falls below this value. The recommended default is MinSpareThreads 10.

    MaxSpareThreads - This directive instructs the server to begin terminating worker threads if the number of idle threads ever exceeds this value. The recommended default is MaxSpareThreads 100.

    MaxThreads - This directive limits the total number of work threads to a maximum value. The recommended default is ThreadsPerChild 250.

    ThreadStackSize - This directive tells the server what size of stack to use for the individual worker thread. The recommended default is ThreadStackSize 65536.

  • The directives that accept filenames as arguments must use NetWare filenames instead of Unix names. However, because Apache uses Unix-style names internally, forward slashes must be used rather than backslashes. It is recommended that all rooted file paths begin with a volume name. If omitted, Apache will assume the SYS: volume which may not be correct.

  • Apache for NetWare has the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2\modules directory. To activate these, or other modules, the LoadModule directive must be used. For example, to active the status module, use the following:

    LoadModule status_module modules/status.nlm

    Information on creating loadable modules is also available.

Additional NetWare specific directives:

  • CGIMapExtension - This directive maps a CGI file extension to a script interpreter.
  • SecureListen - Enables SSL encryption for a specified port.
  • NWSSLTrustedCerts - Adds trusted certificates that are used to create secure connections to proxied servers.
  • NWSSLUpgradeable - Allow a connection created on the specified address/port to be upgraded to an SSL connection.

Compiling Apache for NetWare

Compiling Apache requires MetroWerks CodeWarrior 6.x or higher. Once Apache has been built, it can be installed to the root of any NetWare volume. The default is the sys:/Apache2 directory.

Before running the server you must fill out the conf directory. Copy the file HTTPD-STD.CONF from the distribution conf directory and rename it to HTTPD.CONF. Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting. Copy over the conf/magic and conf/mime.types files as well. Alternatively, a complete distribution can be built by including the keyword install when invoking the makefiles.

Requirements:

The following development tools are required to build Apache 2.0 for NetWare:

  • Metrowerks CodeWarrior 6.0 or higher with the NetWare PDK 3.0 or higher.
  • NetWare Libraries for C (LibC)
  • LDAP Libraries for C
  • ZLIB Compression Library source code
  • AWK utility (awk, gawk or similar). AWK can be downloaded from http://developer.novell.com/ndk/apache.htm. The utility must be found in your windows path and must be named awk.exe.
  • To build using the makefiles, you will need GNU make version 3.78.1 (GMake) available at http://developer.novell.com/ndk/apache.htm.

Building Apache using the NetWare makefiles:

  • Set the environment variable NOVELLLIBC to the location of the NetWare Libraries for C SDK, for example:

    Set NOVELLLIBC=c:\novell\ndk\libc

  • Set the environment variable METROWERKS to the location where you installed the Metrowerks CodeWarrior compiler, for example:

    Set METROWERKS=C:\Program Files\Metrowerks\CodeWarrior

    If you installed to the default location C:\Program Files\Metrowerks\CodeWarrior, you don't need to set this.
  • Set the environment variable LDAPSDK to the location where you installed the LDAP Libraries for C, for example:

    Set LDAPSDK=c:\Novell\NDK\cldapsdk\NetWare\libc

  • Set the environment variable ZLIBSDK to the location where you installed the source code for the ZLib Library, for example:

    Set ZLIBSDK=D:\NOVELL\zlib

  • Set the environment variable PCRESDK to the location where you installed the source code for the PCRE Library, for example:

    Set PCRESDK=D:\NOVELL\pcre

  • Set the environment variable AP_WORK to the full path of the httpd source code directory.

    Set AP_WORK=D:\httpd-2.0.x

  • Set the environment variable APR_WORK to the full path of the apr source code directory. Typically \httpd\srclib\apr but the APR project can be outside of the httpd directory structure.

    Set APR_WORK=D:\apr-1.x.x

  • Set the environment variable APU_WORK to the full path of the apr-util source code directory. Typically \httpd\srclib\apr-util but the APR-UTIL project can be outside of the httpd directory structure.

    Set APU_WORK=D:\apr-util-1.x.x

  • Make sure that the path to the AWK utility and the GNU make utility (gmake.exe) have been included in the system's PATH environment variable.
  • Download the source code and unzip to an appropriate directory on your workstation.
  • Change directory to \httpd-2.0 and build the prebuild utilities by running "gmake -f nwgnumakefile prebuild". This target will create the directory \httpd-2.0\nwprebuild and copy each of the utilities to this location that are necessary to complete the following build steps.
  • Copy the files \httpd-2.0\nwprebuild\GENCHARS.nlm and \httpd-2.0\nwprebuild\DFTABLES.nlm to the SYS: volume of a NetWare server and run them using the following commands:

    SYS:\genchars > sys:\test_char.h
    SYS:\dftables sys:\chartables.c

  • Copy the files test_char.h and chartables.c to the directory \httpd-2.0\os\netware on the build machine.
  • Change directory to \httpd-2.0 and build Apache by running "gmake -f nwgnumakefile". You can create a distribution directory by adding an install parameter to the command, for example:

    gmake -f nwgnumakefile install

Additional make options

  • gmake -f nwgnumakefile

    Builds release versions of all of the binaries and copies them to a \release destination directory.

  • gmake -f nwgnumakefile DEBUG=1

    Builds debug versions of all of the binaries and copies them to a \debug destination directory.

  • gmake -f nwgnumakefile install

    Creates a complete Apache distribution with binaries, docs and additional support files in a \dist\Apache2 directory.

  • gmake -f nwgnumakefile prebuild

    Builds all of the prebuild utilities and copies them to the \nwprebuild directory.

  • gmake -f nwgnumakefile installdev

    Same as install but also creates a \lib and \include directory in the destination directory and copies headers and import files.

  • gmake -f nwgnumakefile clean

    Cleans all object files and binaries from the \release.o or \debug.o build areas depending on whether DEBUG has been defined.

  • gmake -f nwgnumakefile clobber_all

    Same as clean and also deletes the distribution directory if it exists.

Additional environment variable options

  • To build all of the experimental modules, set the environment variable EXPERIMENTAL:

    Set EXPERIMENTAL=1

  • To build Apache using standard BSD style sockets rather than Winsock, set the environment variable USE_STDSOCKETS:

    Set USE_STDSOCKETS=1

Building mod_ssl for the NetWare platform

By default Apache for NetWare uses the built-in module mod_nw_ssl to provide SSL services. This module simply enables the native SSL services implemented in NetWare OS to handle all encryption for a given port. Alternatively, mod_ssl can also be used in the same manner as on other platforms.

Before mod_ssl can be built for the NetWare platform, the OpenSSL libraries must be provided. This can be done through the following steps:

  • Download the recent OpenSSL 0.9.8 release source code from the OpenSSL Source page (older 0.9.7 versions need to be patched and are therefore not recommended).
  • Edit the file NetWare/set_env.bat and modify any tools and utilities paths so that they correspond to your build environment.
  • From the root of the OpenSSL source directory, run the following scripts:

    Netware\set_env netware-libc
    Netware\build netware-libc

    For performance reasons you should enable to build with ASM code. Download NASM from the SF site. Then configure OpenSSL to use ASM code:

    Netware\build netware-libc nw-nasm enable-mdc2 enable-md5

    Warning: dont use the CodeWarrior Assembler - it produces broken code!
  • Before building Apache, set the environment variable OSSLSDK to the full path to the root of the openssl source code directory, and set WITH_MOD_SSL to 1.

    Set OSSLSDK=d:\openssl-0.9.8x
    Set WITH_MOD_SSL=1

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Running a High-Performance Web Server on HPUX - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Running a High-Performance Web Server on HPUX

Date: Wed, 05 Nov 1997 16:59:34 -0800
From: Rick Jones <raj@cup.hp.com>
Reply-To: raj@cup.hp.com
Organization: Network Performance
Subject: HP-UX tuning tips

Here are some tuning tips for HP-UX to add to the tuning page.

For HP-UX 9.X: Upgrade to 10.20
For HP-UX 10.[00|01|10]: Upgrade to 10.20

For HP-UX 10.20:

Install the latest cumulative ARPA Transport Patch. This will allow you to configure the size of the TCP connection lookup hash table. The default is 256 buckets and must be set to a power of two. This is accomplished with adb against the *disc* image of the kernel. The variable name is tcp_hash_size. Notice that it's critically important that you use "W" to write a 32 bit quantity, not "w" to write a 16 bit value when patching the disc image because the tcp_hash_size variable is a 32 bit quantity.

How to pick the value? Examine the output of ftp://ftp.cup.hp.com/dist/networking/tools/connhist and see how many total TCP connections exist on the system. You probably want that number divided by the hash table size to be reasonably small, say less than 10. Folks can look at HP's SPECweb96 disclosures for some common settings. These can be found at http://www.specbench.org/. If an HP-UX system was performing at 1000 SPECweb96 connections per second, the TIME_WAIT time of 60 seconds would mean 60,000 TCP "connections" being tracked.

Folks can check their listen queue depths with ftp://ftp.cup.hp.com/dist/networking/misc/listenq.

If folks are running Apache on a PA-8000 based system, they should consider "chatr'ing" the Apache executable to have a large page size. This would be "chatr +pi L <BINARY>". The GID of the running executable must have MLOCK privileges. Setprivgrp(1m) should be consulted for assigning MLOCK. The change can be validated by running Glance and examining the memory regions of the server(s) to make sure that they show a non-trivial fraction of the text segment being locked.

If folks are running Apache on MP systems, they might consider writing a small program that uses mpctl() to bind processes to processors. A simple pid % numcpu algorithm is probably sufficient. This might even go into the source code.

If folks are concerned about the number of FIN_WAIT_2 connections, they can use nettune to shrink the value of tcp_keepstart. However, they should be careful there - certainly do not make it less than oh two to four minutes. If tcp_hash_size has been set well, it is probably OK to let the FIN_WAIT_2's take longer to timeout (perhaps even the default two hours) - they will not on average have a big impact on performance.

There are other things that could go into the code base, but that might be left for another email. Feel free to drop me a message if you or others are interested.

sincerely,

rick jones

http://www.netperf.org/netperf/


The Apache EBCDIC Port - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

The Apache EBCDIC Port

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.

Overview of the Apache EBCDIC Port

Version 1.3 of the Apache HTTP Server was the first version which included a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

(It is the SIEMENS family of mainframes running the BS2000/OSD operating system. This mainframe OS nowadays features a SVR4-derived POSIX subsystem).

The port was started initially to

  • prove the feasibility of porting the Apache HTTP server to this platform
  • find a "worthy and capable" successor for the venerable CERN-3.0 daemon (which was ported a couple of years ago), and to
  • prove that Apache's preforking process model can on this platform easily outperform the accept-fork-serve model used by CERN by a factor of 5 or more.

This document serves as a rationale to describe some of the design decisions of the port to this machine.

Design Goals

One objective of the EBCDIC port was to maintain enough backwards compatibility with the (EBCDIC) CERN server to make the transition to the new server attractive and easy. This required the addition of a configurable method to define whether a HTML document was stored in ASCII (the only format accepted by the old server) or in EBCDIC (the native document format in the POSIX subsystem, and therefore the only realistic format in which the other POSIX tools like grep or sed could operate on the documents). The current solution to this is a "pseudo-MIME-format" which is intercepted and interpreted by the Apache server (see below). Future versions might solve the problem by defining an "ebcdic-handler" for all documents which must be converted.

Technical Solution

Since all Apache input and output is based upon the BUFF data type and its methods, the easiest solution was to add the conversion to the BUFF handling routines. The conversion must be settable at any time, so a BUFF flag was added which defines whether a BUFF object has currently enabled conversion or not. This flag is modified at several points in the HTTP protocol:

  • set before a request is received (because the request and the request header lines are always in ASCII format)
  • set/unset when the request body is received - depending on the content type of the request body (because the request body may contain ASCII text or a binary file)
  • set before a reply header is sent (because the response header lines are always in ASCII format)
  • set/unset when the response body is sent - depending on the content type of the response body (because the response body may contain text or a binary file)

Porting Notes

  1. The relevant changes in the source are #ifdef'ed into two categories:

    #ifdef CHARSET_EBCDIC

    Code which is needed for any EBCDIC based machine. This includes character translations, differences in contiguity of the two character sets, flags which indicate which part of the HTTP protocol has to be converted and which part doesn't etc.

    #ifdef _OSD_POSIX

    Code which is needed for the SIEMENS BS2000/OSD mainframe platform only. This deals with include file differences and socket implementation topics which are only required on the BS2000/OSD platform.

  2. The possibility to translate between ASCII and EBCDIC at the socket level (on BS2000 POSIX, there is a socket option which supports this) was intentionally not chosen, because the byte stream at the HTTP protocol level consists of a mixture of protocol related strings and non-protocol related raw file data. HTTP protocol strings are always encoded in ASCII (the GET request, any Header: lines, the chunking information etc.) whereas the file transfer parts (i.e., GIF images, CGI output etc.) should usually be just "passed through" by the server. This separation between "protocol string" and "raw data" is reflected in the server code by functions like bgets() or rvputs() for strings, and functions like bwrite() for binary data. A global translation of everything would therefore be inadequate.

    (In the case of text files of course, provisions must be made so that EBCDIC documents are always served in ASCII)

  3. This port therefore features a built-in protocol level conversion for the server-internal strings (which the compiler translated to EBCDIC strings) and thus for all server-generated documents. The hard coded ASCII escapes \012 and \015 which are ubiquitous in the server code are an exception: they are already the binary encoding of the ASCII \n and \r and must not be converted to ASCII a second time. This exception is only relevant for server-generated strings; and external EBCDIC documents are not expected to contain ASCII newline characters.

  4. By examining the call hierarchy for the BUFF management routines, I added an "ebcdic/ascii conversion layer" which would be crossed on every puts/write/get/gets, and a conversion flag which allowed enabling/disabling the conversions on-the-fly. Usually, a document crosses this layer twice from its origin source (a file or CGI output) to its destination (the requesting client): file -> Apache, and Apache -> client.

    The server can now read the header lines of a CGI-script output in EBCDIC format, and then find out that the remainder of the script's output is in ASCII (like in the case of the output of a WWW Counter program: the document body contains a GIF image). All header processing is done in the native EBCDIC format; the server then determines, based on the type of document being served, whether the document body (except for the chunking information, of course) is in ASCII already or must be converted from EBCDIC.

  5. For Text documents (MIME types text/plain, text/html etc.), an implicit translation to ASCII can be used, or (if the users prefer to store some documents in raw ASCII form for faster serving, or because the files reside on a NFS-mounted directory tree) can be served without conversion.

    Example:

    to serve files with the suffix .ahtml as a raw ASCII text/html document without implicit conversion (and suffix .ascii as ASCII text/plain), use the directives:

    AddType text/x-ascii-html .ahtml
    AddType text/x-ascii-plain .ascii

    Similarly, any text/foo MIME type can be served as "raw ASCII" by configuring a MIME type "text/x-ascii-foo" for it using AddType.

  6. Non-text documents are always served "binary" without conversion. This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU file types. This of course requires the user to copy them to the mainframe host using the "rcp -b" binary switch.

  7. Server parsed files are always assumed to be in native (i.e., EBCDIC) format as used on the machine, and are converted after processing.

  8. For CGI output, the CGI script determines whether a conversion is needed or not: by setting the appropriate Content-Type, text files can be converted, or GIF output can be passed through unmodified. An example for the latter case is the wwwcount program which we ported as well.

Document Storage Notes

Binary Files

All files with a Content-Type: which does not start with text/ are regarded as binary files by the server and are not subject to any conversion. Examples for binary files are GIF images, gzip-compressed files and the like.

When exchanging binary files between the mainframe host and a Unix machine or Windows PC, be sure to use the ftp "binary" (TYPE I) command, or use the rcp -b command from the mainframe host (the -b switch is not supported in unix rcp's).

Text Documents

The default assumption of the server is that Text Files (i.e., all files whose Content-Type: starts with text/) are stored in the native character set of the host, EBCDIC.

Server Side Included Documents

SSI documents must currently be stored in EBCDIC only. No provision is made to convert it from ASCII before processing.

Apache Modules' Status

Module | Status | Notes
core | + |
mod_access | + |
mod_actions | + |
mod_alias | + |
mod_asis | + |
mod_auth | + |
mod_authn_anon | + |
mod_authn_dbm | ? | with own libdb.a
mod_authz_dbm | ? | with own libdb.a
mod_autoindex | + |
mod_cern_meta | ? |
mod_cgi | + |
mod_digest | + |
mod_dir | + |
mod_so | - | no shared libs
mod_env | + |
mod_example | - | (test bed only)
mod_expires | + |
mod_headers | + |
mod_imagemap | + |
mod_include | + |
mod_info | + |
mod_log_agent | + |
mod_log_config | + |
mod_log_referer | + |
mod_mime | + |
mod_mime_magic | ? | not ported yet
mod_negotiation | + |
mod_proxy | + |
mod_rewrite | + | untested
mod_setenvif | + |
mod_speling | + |
mod_status | + |
mod_unique_id | + |
mod_userdir | + |
mod_usertrack | ? | untested

Third Party Modules' Status

Module | Status | Notes
mod_jserv | - | JAVA still being ported.
mod_php3 | + | mod_php3 runs fine, with LDAP and GD and FreeType libraries.
mod_put | ? | untested
mod_session | - | untested


Sunucu ve Destek Programları - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Sunucu ve Destek Programları

Bu sayfada Apache HTTP Sunucusuna dahil tüm çalıştırılabilir programlar tanıtılmıştır.

Dizin

httpd
Apache hiper metin aktarım protokolü sunucusu.
apachectl
Apache HTTP Sunucusu denetim arayüzü.
ab
Apache HTTP Sunucusu başarım ölçme aracı.
apxs
Apache HTTP Sunucusu eklenti aracı (APache eXtenSion tool).
configure
Kaynak ağacını yapılandırır.
dbmmanage
Kullanıcı kimlik doğrulama dosyalarını temel kimlik doğrulaması için DBM biçeminde oluşturur ve günceller.
fcgistarter
Bir FastCGI programını çalıştırır.
htcacheclean
Disk arabelleğini temizler.
htdigest
Kullanıcı kimlik doğrulama dosyalarını özet kimlik doğrulaması için oluşturur ve günceller.
htdbm
DBM parola veritabanlarını idare eder.
htpasswd
Kullanıcı kimlik doğrulama dosyalarını temel kimlik doğrulaması için oluşturur ve günceller.
httxt2dbm
RewriteMap ile kullanmak üzere DBM dosyaları oluşturur.
logresolve
Apache günlük dosyalarındaki IP adreslerini konak isimlerine dönüştürür.
log_server_status
Sunucunun durumunu düzenli aralıklarla günlüğe kaydeder.
rotatelogs
Sunucuyu öldürmek gerekmeksizin günlük dosyalarının döndürülmesini sağlar.
split-logfile
Bir çok konaklı günlük dosyasını konak başına bir günlük dosyası düşecek şekilde böler.
suexec
Bir dosyayı belli bir kullanıcı adına çalıştırır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


httpd - Apache Hiper Metin Aktarım Protokolü Sunucusu - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

httpd - Apache Hiper Metin Aktarım Protokolü Sunucusu

httpd, Apache Hiper Metin Aktarım Protokolü (HTTP) sunucusu programıdır. Tek başına çalışan bir artalan süreci olarak tasarlanmıştır. Bu tarz kullanıldığında istekleri işleme sokmak için çocuk süreçlerden ve evrelerden oluşan bir havuz oluşturur.

Genelde, httpd'nin doğrudan çağrılmaması gerekir. Unix ve benzerlerinde apachectl aracılığıyla, Windows NT, 2000 ve XP'de bir hizmet olarak, Windows 9x ve ME'de ise bir konsol uygulaması olarak çalıştırılır.

Ayrıca bakınız:

  • Apache httpd'nin Başlatılması
  • Apache httpd'nin Durdurulması
  • Yapılandırma Dosyaları
  • Platforma Özgü Belgeler
  • apachectl

Kullanım

httpd [ -d sunucu-kök-dizini ] [ -f yapılandırma-dosyası ] [ -C yönerge ] [ -c yönerge ] [ -D parametre ] [ -e seviye ] [ -E dosya ] [ -k start | restart | graceful | stop | graceful-stop ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ] [ -M ] [ -T ]

Windows sistemlerinde, ek olarak şunlar vardır:

httpd [ -k install | config | uninstall ] [ -n isim ] [ -w ]

Seçenekler

-d sunucu-kök-dizini
sunucu-kök-dizini'ni ServerRoot yönergesine ilk değer olarak atar. Yapılandırma dosyasındaki bir ServerRoot yönergesiyle bu atama geçersiz kılınabilir. Bu seçenek belirtilmediği takdirde /usr/local/apache2 dizini öntanımlıdır.
-f yapılandırma-dosyası
Başlatma sırasında yapılandırma-dosyası'ndaki yönergeler kullanılır. Eğer yapılandırma-dosyası bir / ile başlamıyorsa dosyanın ServerRoot yönergesinin değerine göreli olduğu varsayılır. Seçenek belirtilmediği takdirde conf/httpd.conf öntanımlı değerdir.
-k start | restart | graceful | stop | graceful-stop
httpd'yi başlatmak, durdurmak ve yeniden başlatmak için sinyal gönderir. Daha ayrıntılı bilgi edinmek için Apache httpd'nin Durdurulması belgesine bakınız.
-C yönerge
Yapılandırma yönerge'sini yapılandırma dosyalarını okumadan önce işleme sokar.
-c yönerge
Yapılandırma yönerge'sini yapılandırma dosyalarını okuduktan sonra işleme sokar.
-D parametre
Sunucu başlatılırken veya yeniden başlatılırken komutları şarta bağlı olarak işleme sokmak veya atlamak için yapılandırma dosyalarında kullanılan <IfDefine> bölümlerinde kullanılmak üzere bir yapılandırma parametre'si tanımlar. Ayrıca, -DNO_DETACH (ana sürecin çatallanmasını engellemek için), -DFOREGROUND (ana sürecin setsid() ve benzerlerinden çağrılmasını engellemek için) gibi daha az bilinen bazı başlatma parametrelerini atamakta da kullanılabilir.
-e seviye
Hata günlüğü seviyesi olarak LogLevel yönergesine sunucu başlatılırken seviye değerini atar. Bu seçenek, başlatma sırasındaki sorunları saptamak amacıyla hata iletilerinin ayrıntı seviyesini geçici olarak arttırmak için kullanılır.
-E dosya
Sunucunun başlatılması sırasında hata iletilerinin belirtilen dosya'ya gönderilmesini sağlar.
-h
Mevcut komut satırı seçeneklerinin kısa bir özetini çıktılar.
-l
Sunucunun içinde derlenmiş modüllerin listesini çıktılar. Bu liste LoadModule yönergesi kullanılarak devingen olarak yüklenen modülleri içermez.
-L
Durağan modüllerce sağlanmış yönergeleri olası değerleriyle geçerli konumlarına yerleştirerek listeler. Paylaşımlı modüllerce sağlanan yönergeleri listelemez.
-M
Yüklü durağan ve paylaşımlı modülleri listeler.
-S
Yapılandırma dosyasından çözümlenmiş haliyle ayarları gösterir (şu an sadece sanal konak ayarları gösterilmektedir).
-T (2.3.8 ve sonrasında kullanılabilmektedir)
Başlatma ve yeniden başlatma sırasında belge kökü sınanmadan geçilir.
-t
Yapılandırma dosyasını sözdizimi hatalarına karşı denetler. Program sözdizimini denetledikten sonra sözdizimi geçerliyse 0 ile, değilse sıfırdan farklı bir değerle çıkar. -DDUMP_VHOSTS seçeneği ile birlikte kullanılmışsa ek olarak sanal konak ayrıntıları da basılır. -DDUMP_MODULES seçeneği ile ise ek olarak tüm modüller listelenir.
-v
httpd sürümünü basar ve çıkar.
-V
Sürümü ve httpd kurulum parametrelerini basar ve çıkar.
-X
httpd hata ayıklama kipinde çalışır. Tek çocuk süreç başlatılır ve sunucu konsolu terketmez.

Aşağıdaki seçenekler sadece Windows platformunda geçerlidir:

-k install | config | uninstall
Parametreler bakımından sırasıyla: Apache httpd bir Windows NT hizmeti haline getirilir; başlatma seçenekleri Apache httpd hizmeti için değiştirilir; ve Apache httpd hizmeti sistemden kaldırılır.
-n isim
Sinyal gönderilecek Apache httpd hizmetinin ismi.
-w
Hata durumunda konsol penceresi açık tutularak hata iletilerinin okunması sağlanır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


ab - Apache HTTP sunucusu başarım ölçme aracı - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

ab - Apache HTTP sunucusu başarım ölçme aracı

ab Apache Hiper Metin Aktarım Protokolü (HTTP) sunucunuzun başarımını ölçmek amacıyla kullanabileceğiniz bir kıyaslama aracıdır. Mevcut Apache kurulumunuzun görevini nasıl yerine getirdiği hakkında bir izlenim edinmeniz için tasarlanmıştır. Özellikle, Apache kurulumunuzun saniyede kaç isteği sunma yeteneğinde olduğunu gösterir.

Ayrıca bakınız:

  • httpd

Kullanım

ab
    [ -A yetkili-kullanıcı:parola ]
    [ -b tampon-boyu ]
    [ -B yerel-adres ]
    [ -c bağlantı-sayısı ]
    [ -C çerez-ismi=değer ]
    [ -d ]
    [ -e csv-dosyası ]
    [ -f protokol ]
    [ -g gnuplot-dosyası ]
    [ -h ]
    [ -H özel-başlık ]
    [ -i ]
    [ -k ]
    [ -l ]
    [ -m HTTP-yöntemi ]
    [ -n istek-sayısı ]
    [ -p POST-dosyası ]
    [ -P vekil-yetkilisi:parola ]
    [ -q ]
    [ -r ]
    [ -s zamanasimi ]
    [ -S ]
    [ -t saniye ]
    [ -T içerik-türü ]
    [ -u PUT-dosyası ]
    [ -v ayrıntı-düzeyi]
    [ -V ]
    [ -w ]
    [ -x <table>-öznitelikleri ]
    [ -X vekil[:port] ]
    [ -y <tr>-öznitelikleri ]
    [ -z <td>-öznitelikleri ]
    [ -Z şifre-kümesi ]
    [http[s]://]konakadı[:port]/dizin

Seçenekler

-A yetkili-kullanıcı:parola
Sunucuya TEMEL Kimlik Doğrulamada kullanılmak üzere kanıt sağlar. Kullanıcı adı ile parola arasına sadece : konur ve sunucunun buna ihtiyacı olup olmadığına bakılmaksızın (yani, bir "401 kimlik doğrulaması gerekli" yanıtı beklenmeden) bağlantı üzerinden base64 kodlu olarak sunucuya gönderilir.
-b tampon-boyu
TCP gönderme/alma tamponlarının bayt cinsinden uzunluğu.
-B yerel-adres
Uzak bağlantılar yaparken dinlenecek adres.
-c bağlantı-sayısı
Aynı anda işleme sokulacak bağlantı sayısı. Aynı anda bir bağlantı öntanımlı değerdir.
-C çerez-ismi=değer
İsteğe bir Cookie: satırı ekler. Argüman olarak genellikle bir isim=değer çifti kullanılır. Bu çiftler birden fazla olabilir.
-d
"percentage served within XX [ms] table" iletisi gösterilmez. (Geriye uyumluluk için vardır).
-e csv-dosyası
Sunulan isteğin birim zamanda (milisaniye) ne kadarının (yüzde cinsinden) sunulduğunu gösteren virgül ayraçlı değerler (CSV) dosyası. Sonuçlar 'bobin haline' getirilmiş olduğundan doğal olarak 'gnuplot' dosyasından daha yararlıdır.
-f protokol
SSL/TLS protokolü belirtilir (SSL2, SSL3, TLS1, TLS1.1, TLS1.2 veya ALL). TLS1.1 ve TLS1.2 desteği 2.4.4 ve sonraki sürümler içindir.
-g gnuplot-dosyası
Ölçülen değerler bir 'gnuplot' veya TSV (sekme ayraçlı değerler) dosyasına yazılır. Bu dosya, Gnuplot, IDL, Mathematica, Igor hatta Excel tarafından veri dosyası olarak kabul edilir. Veri sütunlarının başlıkları dosyanın ilk satırında bulunur.
-h
Kullanım bilgisi gösterir.
-H özel-başlık
İsteğe fazladan başlık ekler. özel-başlık, aralarında iki nokta imi bulunan bir isim-değer çifti olarak belirtilir. Örnek: "Accept-Encoding: zip/zop;8bit"
-i
GET istekleri yerine HEAD istekleri yapılır.
-k
HTTP KeepAlive (kalıcı bağlantı) özelliğini etkinleştirir, yani tek bir oturum içinde çok sayıda isteğe hizmet sunulabilir. Özellik öntanımlı olarak kapalıdır.
-l
Yanıtarın uzunluğu sabit değilse hataları raporlamaz. Özdevinimli sayfalarda kullanışlı olabilir. 2.4.7 ve sonraki sürümler içindir.
-m HTTP-yöntemi
İstekler için özel HTTP yöntemi, belirtilir. 2.4.10 ve sonraki sürümler içindir.
-n istek-sayısı
Kıyaslama oturumu sırasında sunucuya uygulanacak istek sayısı. Öntanımlı olarak hiçbir başarım ölçütü sağlamayan tek bir istek yapılır.
-p POST-dosyası
POST isteği ile ilgili verileri içeren dosya. Ayrıca -T seçeneğini de belirtmeyi unutmayın..
-P vekil-yetkilisi:parola
Vekil sunucuya TEMEL Kimlik Doğrulamasında kullanılacak kanıtları sağlar. Kullanıcı adı ile parola arasına sadece : konur ve vekilin buna ihtiyacı olup olmadığına bakılmaksızın (yani, bir "407 vekilde kimlik doğrulaması gerekiyor" yanıtı beklenmeden) bağlantı üzerinden base64 kodlu olarak sunucuya gönderilir.
-q
İstek sayısı 150'den fazla olduğunda, ab her 100 veya %10 istekte bir, standart hataya bir işlenen istek sayacı çıktılar. -q seçeneği bu çıktının üretilmemesini sağlar.
-r
Soket hata alsa bile program çıkmaz.
-s zamanasimi
Soket zaman aşımına uğramadan önce beklenecek azami saniye sayısı. 30 saniye öntanımlı süredir. 2.4.4 ve sonraki sürümler içindir.
-S
Ortalama ve ortanca değerler arasında bir veya iki standart sapmadan fazlası varsa ne ortalama değer ne standart sapma değeri ne de uyarı/hata iletileri gösterilir. Öntanımlı olarak, asgari/ortalama/azami değerler gösterilir. (Geriye uyumluluk).
-t saniye
Ölçümleme işleminin ne kadar süreyle uygulanacağı belirtilir. Dahili olarak -n 50000 seçeneği uygulanır. Bunu belli bir süreye göre kıyaslama yapmak amacıyla kullanabilirsiniz. Öntanımlı olarak bir süre kısıtlaması yoktur.
-T içerik-türü
POST/PUT verisi için kullanılacak içerik türü belirtilir. Örnek: application/x-www-form-urlencoded. Öntanımlı değer: text/plain.
-v ayrıntı-düzeyi
Çıktının ayrıntı düzeyi belirtilir. 4 ve üstü ile başlıklar hakkında bilgi, 3 ve üstü ile yanıt kodları (404, 200, vb.), 2 ve üstü ile ise uyarı ve bilgi iletileri gösterilir.
-u PUT-dosyası
PUT verisini içeren dosya. Ayrıca, -T seçeneğini belirtmeyi de unutmayın.
-V
Sürüm bilgilerini gösterir ve çıkar.
-w
Sonuçları HTML tabloları olarak basar. Öntanımlı tablo, beyaz artalanlı ve iki sütunludur.
-x <table>-öznitelikleri
<table> etiketinde kullanılacak öznitelikler belirtilir. Belirtilen öznitelikler etiket içine <table buraya > biçeminde yerleştirilir.
-X vekil[:port]
İstekler için bir vekil sunucu kullanılır.
-y <tr>-öznitelikleri
<tr> etiketinde kullanılacak öznitelikler belirtilir.
-z <td>-öznitelikleri
<td> etiketinde kullanılacak öznitelikler belirtilir.
-Z şifre-kümesi
SSL/TLS şifre kümesi belirtilir (openssl(1) şifrelerine bakınız).

Çıktı

Aşağıda ab tarafından döndürülen değerler açıklanmıştır:

Server Software
İlk başarılı yanıtın, varsa, server HTTP başlığında döndürülen değer. Bu başlıktaki başlangıçtan 32 ondalık değerli karaktere (genellikle boşluk veya CR/LF karakteri) kadar tüm karakterleri içerir.
Server Hostname
Komut satırında belirtilen DNS veya IP adresi.
Server Port
ab'nin bağlandığı port. Komut satırında port belirtilmemişse, öntanımlı olarak http için 80, https için 443'tür.
SSL/TLS Protocol
İstemci le sunucu arasında uzlaşılmış protokol değerleri. Bu sadece SSL kullanılıyorsa çıktılanır.
Document Path
Komut satırı dizgesinden çözümlenen isteğin URI'si.
Document Length
Başarıyla döndürülen ilk belgenin bayt cinsinden uzunluğu. Eğer belge uzunluğu sınama sırasında değişirse yanıt bir hata içerecektir.
Concurrency Level
Sınama sırasında kullanılan eşzamanlı istemcilerin sayısı.
Time taken for tests
İlk soket bağlantısının alındığı andan son yanıtın alındığı ana kadar geçen süre.
Complete requests
Alınan başarılı yanıtların sayısı.
Failed requests
Başarısızlık olarak addedilen isteklerin sayısı. Sayı sıfırdan büyükse, diğer satırda, bağlanma, okuma, yanlış içerik uzunluğu, istisnalar gibi sebeplerle başarısız olmuş istekler gösterilir.
Write errors
Başarısız yazma hatalarının (kırık boru) sayısı.
Non-2xx responses
200 serisi yanıt kodları ile açıklanamayan yanıtların sayısı. Tüm yanıtlar 200 olursa bu alan çıktılanmaz.
Keep-Alive requests
Keep-Alive isteklerinde sonuçlanan bağlantı sayısı.
Total body sent
Sınamanın parçası olarak veri gönderimi yapılandırılmışsa, bu sınama sırasında gönderilen toplam bayt sayısıdır. Sınama sırasında gövde gönderilmiyorsa bu alan çıktılanmaz.
Total transferred
Sunucudan alınan toplam bayt sayısı. Bu sayı aslında hattan gönderilen bayt sayısıdır.
HTML transferred
Sunucudan alınan belge baytlarının sayısı. Bu sayı HTTP başlıklarının bayt sayısını içermez.
Requests per second
Saniyedeki istek sayısı. İstek sayısının toplam süreye oranıdır.
Time per request
İstek başına harcanan süre. İlk değer eşzamanlılık * süre * 1000 / biten formülüyle hesaplanırken ikincisi için süre * 1000 / biten formülü kullanılır.
Transfer rate
okunantoplam / 1024 / süre formülüyle hesaplanan aktarım hızı.

Börtü böcek

Duruk bildirimli sabit uzunlukta çeşitli tamponlar vardır. Sunucudan gelen yanıt başlıkları ve diğer harici girdiler, komut satırı argümanları ile birlikte basitçe çözümlenir, bu size can sıkıcı gelebilir.

HTTP/1.x protokolünü tamamen gerçeklemez; sadece yanıtların 'belli başlı' bazı biçimlerini kabul eder. Aksi takdirde, strstr(3) işlevinin yoğun kullanımı nedeniyle sunucu yerine ab'nin başarımını ölçerdiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


apachectl - Apache HTTP Sunucusu Denetim Arayüzü - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

apachectl - Apache HTTP Sunucusu Denetim Arayüzü

apachectl Apache Hiper Metin Aktarım Protokolü (HTTP) sunucusu için bir denetim aracıdır. Sistem yöneticisinin Apache httpd artalan sürecini denetimi altında tutabilmesine yardımcı olmak amacıyla tasarlanmıştır.

apachectl iki kipte işleyebilir. İlkinde, httpd komutu için basit bir önyüz gibi davranarak, gerekli ortam değişkenlerini atar ve belirtilen komut satırı seçenekleriyle httpd sürecini başlatır. İkinci kipte ise, apachectl bir SysV başlatma betiği olarak start, restart, stop gibi tek sözcüklük basit argümanlar alır ve bunları uygun sinyallere dönüştürerek httpd'ye gönderir.

Eğer Apache kurulumunuzda standart dışı dosya yolları kullanmışsanız, httpd programına uygun yolları atamak için apachectl betiğini elden geçirmelisiniz. Bu arada gerek gördüğünüz httpd komut satırı argümanlarını da belirtebilirsiniz. Ayrıntılar için betik içindeki açıklamalara bakınız.

apachectl betiği başarı durumunda 0 çıkış değeri ile döner. Bir hata durumunda ise sıfırdan farklı bir değerle döner. Daha fazla bilgi için betik içindeki açıklamalara bakınız.

Ayrıca bakınız:

  • Apache'nin Başlatılması
  • Apache'nin Durdurulması
  • Yapılandırma Dosyaları
  • Platform Belgeleri
  • httpd

Kullanım

apachectl önyüz kipinde çalıştığında httpd programının bütün komut satırı argümanlarını kabul edebilir.

apachectl [ httpd-argümanları ]

SysV başlatma betiği kipinde ise, apachectl aşağıda tanımlanan basit, tek sözcüklük komutları kabul eder.

apachectl komut

Seçenekler

Burada sadece SysV başlatma betiğine özgü seçeneklere yer verilmiştir. Diğer argümanlar için httpd kılavuz sayfasına bakınız.

start
Apache httpd artalan sürecini başlatır. Zaten çalışmaktaysa bir hata verir. apachectl -k start komutuna eşdeğerdir.
stop
Apache httpd artalan sürecini durdurur. apachectl -k stop komutuna eşdeğerdir.
restart
Apache httpd artalan sürecini yeniden başlatır; çalışmıyorsa çalıştırılır. Artalan sürecinin ölü olmadığından emin olmak için yeniden başlatmadan önce configtest seçeneği verilmiş gibi yapılandırma dosyaları sınanır. apachectl -k restart komutuna eşdeğerdir.
fullstatus
mod_status üzerinden tam bir durum raporu gösterir. Bunun çalışması için sunucuda mod_status etkinleştirilmiş olmalı ve sisteminizde lynx gibi bir metin kipi HTTP tarayıcı kurulu olmalıdır. Durum raporuna erişmek için kullanılacak adres betik içinde STATUSURL değişkenine atanabilir.
status
Özet halinde bir durum raporu gösterir. O an sunulmakta olan isteklerin gösterilmemesi dışında fullstatus seçeneği gibidir.
graceful
Apache httpd artalan sürecini nazikçe yeniden başlatır; çalışmıyorsa çalıştırılır. O an hizmet sunmakta olan çocuk süreçleri hemen durdurmaması dışında normal yeniden başlatma gibidir. Bir yan etki olarak eski günlük dosyaları hemen kapatılmaz. Yani, günlük dosyalarını döndüren bir betik kullanıyorsanız yenilerini başlatmadan önce eski dosyaların tamamen kapandığından emin olmak için belli bir süre beklemeniz gerekecektir. Artalan sürecinin ölü olmadığından emin olmak için yeniden başlatmadan önce configtest seçeneği verilmiş gibi yapılandırma dosyaları sınanır. apachectl -k graceful komutuna eşdeğerdir.
graceful-stop
Apache httpd artalan sürecini nazikçe durdurur. O an hizmet sunmakta olan çocuk süreçleri hemen durdurmaması dışında normal durdurma gibidir. Bir yan etki olarak eski günlük dosyaları hemen kapatılmaz. apachectl -k graceful-stop komutuna eşdeğerdir.
configtest
Yapılandırma dosyasında sözdizimi denetimi yapılmasını sağlar. Yapılandırma dosyaları çözümlenir ve bir sorun yoksa bir Syntax Ok raporu verilir fakat, bir hata varsa o hataya ilişkin ayrıntılı bilgi verilir. apachectl -t komutuna eşdeğerdir.

Aşağıdaki seçenek eski sürümlerde kullanılmaktaydı, fakat artık kullanılmamaktadır.

startssl
httpd programını SSL destekli başlatmak için, yapılandırma dosyanızı ilgili yönergeleri içermesi için elden geçirmeli ve normal apachectl start komutunu kullanmalısınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


apxs - Apache Eklenti Aracı - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

apxs - Apache Eklenti Aracı

apxs, Apache Hiper Metin Aktarım Protokolü (HTTP) sunucusu için ek modül derleme ve kurulum aracıdır. Bu araç sayesinde, bir veya daha fazla kaynak veya nesne dosyasından bir devingen paylaşımlı nesne (DSO - "Dynamic Shared Object" kısaltması) derlemek ve bu nesneyi (modülü) Apache sunucusuna çalışma anında mod_so modülünün LoadModule yönergesi üzerinden yüklemek mümkün olmaktadır.

Bu eklenti mekanizmasını platformunuzda kullanmak için DSO desteğinin olması ve httpd programının mod_so modülünü içerecek şekilde derlenmiş olması gerekir. Eğer bunlar mevcut değilse apxs aracı durumu size bildirecektir. Bunu aşağıdaki komutla kendiniz de sınayabilirsiniz:

$ httpd -l

mod_so modülü gösterilen listede yer almalıdır. Bu gereksinimler sağlandığı takdirde apxs aracı sayesinde DSO mekanizması üzerinden kendi modüllerinizi kurmak suretiyle Apache sunucunuzun işlevselliğini kolayca arttırabilirsiniz. Örnek bir uygulama:

$ apxs -i -a -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/dosya/yolu/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
cp mod_foo.so /dosya/yolu/apache/modules/mod_foo.so
chmod 755 /dosya/yolu/apache/modules/mod_foo.so
[`foo' modülü /dosya/yolu/apache/etc/httpd.conf'ta etkinleştiriliyor]
$ apachectl restart
/dosya/yolu/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/dosya/yolu/apache/sbin/apachectl restart: httpd started
$ _

dosya olarak bir C kaynak dosyası (.c), bir nesne dosyası (.o) ve hatta bir kütüphane arşivi archive (.a) belirtebilirsiniz. apxs aracı bu dosya uzantılarını tanıdığından C dosyalarını derleme işleminden, arşiv ve nesne dosyalarını ise doğrudan ilintileme işleminden geçirir. Fakat böyle önceden derlenmiş nesne dosyalarını kullanırken, devingen paylaşımlı nesne olarak kullanılmalarını sağlamak üzere konumdan bağımsız kod (PIC) üretecek şekilde derlenmiş olduklarından emin olmalısınız. Örneğin GCC'yi bunun için daima -fpic seçeneği ile kullanmalısınız. Diğer C derleyiciler için, apxs'in nesne dosyalarını derlerken kullanacağı seçenekleri öğrenmek için o derleyicilerin kılavuz sayfalarına bakınız.

Apache'deki DSO desteği ile ilgili daha ayrıntılı bilgi edinmek için mod_so belgesini okumakla yetinmeyip src/modules/standard/mod_so.c kaynak dosyasını da okuyunuz.

Ayrıca bakınız:

  • apachectl
  • httpd

Kullanım

apxs -g [ -S isim=değer ] -n modüladı

apxs -q [ -v ] [ -S isim=değer ] sorgu ...

apxs -c
    [ -S isim=değer ]
    [ -o dso-dosyası ]
    [ -I include-dizini ]
    [ -D isim=değer ]
    [ -L lib-dizini ]
    [ -l kütüphane-adı ]
    [ -Wc,derleyici-seçenekleri ]
    [ -Wl,ilintileyici-seçenekleri ]
    [ -p ]
    dosya ...

apxs -i
    [ -S isim=değer ]
    [ -n modüladı ]
    [ -a ]
    [ -A ]
    dso-dosyası ...

apxs -e
    [ -S isim=değer ]
    [ -n modüladı ]
    [ -a ]
    [ -A ]
    dso-dosyası ...

Seçenekler

Ortak Seçenekler

-n modüladı
-i (kurulum) ve -g (şablon üretimi) seçenekleri için modül ismi belirtmek amacıyla kullanılır. Bir modül ismi belirtmek için bu seçeneği kullanın. -g seçeneği için bu gereklidir. -i seçeneği için ise araç, modül ismini kaynağın ismine bakarak veya (son çare olarak) dosya isminden tahmin etmeye çalışarak saptamaya çalışır.

Sorgu Seçenekleri

-q sorgu
httpd'yi derlemekte kullanılacak değişkenler ve ortam ayarları için bir sorgu gerçekleştirir. When invoked without sorgu belirtilmeksizin çağrıldığında, bilinen değişkenleri değerleriyle birlikte basar. İsteğe bağlı -v seçeneği liste çıktısını biçemler.

Modülünüzü yükleyecek httpd'yi derlemek için kullanılacak ayarları elle belirtmek için kullanılır. Örneğin, Apache'nin C başlık dosyalarının yerini kendi Makefile dosyalarınızın içinde şöyle belirtebilirsiniz:

INC=-I`apxs -q INCLUDEDIR`

Yapılandırma Seçenekleri

-S isim=değer
Bu seçenek yukarıda açıklanan apxs ayarlarını değiştirir.

Şablon Üretme Seçenekleri

-g
modüladı (-n seçeneğine bakınız) adında bir alt dizin oluşturur ve içine iki dosya yerleştirir: Kendi modülünüzü oluşturabilmeniz için veya apxs mekanizmaları ile hemen oynamaya başlayabilmeniz için mod_modüladı.c adında bir modül kaynak dosyası örneği ve bu modülü derleyip kurmayı kolaylaştırmak için bir Makefile dosyası.

DSO Derleme Seçenekleri

-c
Bu seçenek derleme yapılacağını belirtir. Önce belirtilen C kaynak dosyalarını (.c), nesne dosyalarını (.o) elde etmek için derler. Sonra bunları kalan nesne dosyaları (.o ve .a) ile ilintileyerek dso-dosyası adında bir devingen paylaşımlı nesne oluşturur. Eğer -o seçeneği ile modül ismi belirtilmemişse dosyalar arasındaki ilk dosyanın ismine bakarak dosya ismi tahmin edilmeye çalışılır ve mod_isim.so dosya adı bu isimden elde edilir.
-o dso-dosyası
Oluşturulacak devingen paylaşımlı nesnenin ismini belirtmek için kullanılır. Modül ismi bu seçenekle belirtilmez ve dosya listesinden bir isim tahmini de yapılamazsa son çare olarak mod_unknown.so ismi kullanılır.
-D isim=değer
Bu seçenek doğrudan derleme komutlarına aktarılır. Bu seçeneği derleme işlemine kendi tanımlarınızı belirtmek için kullanın.
-I include-dizini
Bu seçenek doğrudan derleme komutlarına aktarılır. Bu seçeneği derleme işleminde kullanılmak üzere kendi başlık dosyalarınızı içeren dizinleri arama yollarına eklemek için kullanın.
-L lib-dizini
Bu seçenek doğrudan derleme komutlarına aktarılır. Bu seçeneği derleme işleminde kullanılmak üzere kendi kütüphane dizinlerinizi arama yollarına eklemek için kullanın.
-l kütüphane-adı
Bu seçenek doğrudan derleme komutlarına aktarılır. Bu seçeneği derleme işleminde kullanılmak üzere kendi kütüphanelerinizi arama yollarına eklemek için kullanın.
-Wc,derleyici-seçenekleri
Bu seçenek libtool --mode=compile komutuna doğrudan seçenek aktarmak için kullanılır. Bu seçeneği yerel derleyiciniz için gereken ek seçenekleri belirtmek için kullanın.
-Wl,ilintileyici-seçenekleri
Bu seçenek libtool --mode=link komutuna doğrudan seçenek aktarmak için kullanılır. Bu seçeneği yerel ilintileyiciniz için gereken ek seçenekleri belirtmek için kullanın.
-p
Bu seçenek apxs'in apr/apr-util kütüphaneleriyle ilintilenmesini sağlar. apr/apr-util kütüphanelerini kullanan yardımcı uygulamaları derlerken yararlıdır.

DSO Kurulum ve Yapılandırma Seçenekleri

-i
Kurulum işlemini belirtir ve devingen olarak paylaşımlı nesneleri sunucunun modules dizinine kurar.
-a
İlgili LoadModule satırını Apache'nin httpd.conf yapılandırma dosyasına özdevinimli olarak ekleyerek veya böyle bir satır varsa bunu etkin kılarak modülü etkinleştirir.
-A
LoadModule yönergesini daha sonra etkinleştirmek üzere satırın başına bir diyez imi (#) yerleştirmesi dışında -a seçeneği ile aynıdır.
-e
Modülü kurmaya çalışmaksızın Apache'nin httpd.conf yapılandırma dosyasını -i işlemine benzer şekilde -a ve -A seçenekleri ile düzenleme işlemini belirtir.

Örnekler

Apache'nin sunucu işlevselliğini genişletmek amacıyla kullanacağınız mod_foo.c adında bir Apache modülünüz olduğunu varsayalım. Öncelikle, C kaynak dosyasını, Apache sunucusuna çalışma anında yüklenmeye uygun bir paylaşımlı nesne olarak derlemeniz gerekir. Bunu sağlamak için şu komutları vermelisiniz:

$ apxs -c mod_foo.c
/dosya/yolu/libtool --mode=compile gcc ... -c mod_foo.c
/dosya/yolu/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
$ _

Bundan sonra, Apache yapılandırmanızın bu paylaşımlı nesneyi yüklemek için bir LoadModule yönergesi içermesini sağlamalısınız. apxs bu adımı basitleştirmek amacıyla, paylaşımlı nesneyi sunucunun modules dizinine özdevinimli olarak kurmak ve httpd.conf dosyasını buna uygun olarak güncellemek için bir yol sağlar. Bu sonuç şöyle elde edilebilir:

$ apxs -i -a mod_foo.la
/dosya/yolu/instdso.sh mod_foo.la /path/to/apache/modules
/dosya/yolu/libtool --mode=install cp mod_foo.la /dosya/yolu/apache/modules ... chmod 755 /dosya/yolu/apache/modules/mod_foo.so
[`foo' modülü /dosya/yolu/apache/conf/httpd.conf'da etkinleştiriliyor]
$ _

Yapılandıma dosyasına (eğer yoksa) şu satır eklenir:

LoadModule foo_module modules/mod_foo.so

Bunu öntanımlı olarak iptal etmek isterseniz -A seçeneğini kullanmanız gerekir:

$ apxs -i -A mod_foo.c

apxs mekanizmalarını hızlıca denemek için örnek bir Apache modül şablonunu ve bir Makefile dosyasını şöyle oluşturabilirsiniz:

$ apxs -g -n foo
Creating [DIR] foo
Creating [FILE] foo/Makefile
Creating [FILE] foo/modules.mk
Creating [FILE] foo/mod_foo.c
Creating [FILE] foo/.deps
$ _

Ardından bu örnek modülü bir paylaşımlı nesne olarak derleyip Apache sunucusuna yükleyebilirsiniz:

$ cd foo
$ make all reload
apxs -c mod_foo.c
/dosya/yolu/libtool --mode=compile gcc ... -c mod_foo.c
/dosya/yolu/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
apxs -i -a -n "foo" mod_foo.la
/dosya/yolu/instdso.sh mod_foo.la /dosya/yolu/apache/modules
/dosya/yolu/libtool --mode=install cp mod_foo.la /dosya/yolu/apache/modules ... chmod 755 /dosya/yolu/apache/modules/mod_foo.so
[`foo' modülü /dosya/yolu/apache/conf/httpd.conf'ta etkinleştiriliyor]
apachectl restart
/dosya/yolu/apache/sbin/apachectl restart: httpd not running, trying to start
chmod 755 /dosya/yolu/apache/modules/mod_foo.so
[`foo' modülü /dosya/yolu/apache/etc/httpd.conf'ta etkinleştiriliyor]
apachectl restart
/dosya/yolu/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/dosya/yolu/apache/sbin/apachectl restart: httpd started
$ _

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


configure - kaynak ağacını yapılandırır - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

configure - kaynak ağacını yapılandırır

configure betiği, Apache HTTP Sunucusunun kaynak kodlarını belli bir platform için yapılandırmakta ve derlemekte kullanılır. Sunucuyu kişisel gereksinimlerinize uygun şekilde derlemek için çeşitli seçeneklere sahiptir.

Bu betik Apache HTTP Sunucusu kaynak paketinin kök dizininde bulunur ve sadece Unix ve benzeri sistemlerde kullanılabilir. Kaynak paketinin diğer platformalarda yapılandırılması ve derlenmesi hakkında bilgi edinmek için platform belgelerine bakınız.

Ayrıca bakınız:

  • Derleme ve Kurulum

Komut Satırı

configure betiğini kaynak paketinin kök dizininden başka bir yere kopyalayıp çalıştırmamalısınız.

./configure [seçenek]... [değişken=değer]...

CC, CFLAGS gibi ortam değişkenlerini değişken=değer atamaları biçiminde kullanabilirsiniz. Kullanışlı değişkenlerin bazıları aşağıda açıklanmıştır.

Seçenekler

  • Yapılandırma seçenekleri
  • Kurulum dizinleri
  • Sistem türleri
  • Seçimlik özellikler
  • Destek programları için seçenekler

Yapılandırma seçenekleri

Aşağıdaki seçenekler configure betiğinin kendi davranışını belirlemekte kullanılır.

-C
--config-cache
--cache-file=config.cache için bir kısaltmadır.
--cache-file=dosya
Sınama sonuçları dosya dosyasında saklanır. Bu seçenek açıkça belirtilmedikçe işlevsizdir.
-h
--help [short|recursive]
Yardım metnini basar ve çıkar. short değeriyle sadece bu pakete özgü seçenekler listelenir. recursive değeriyle ise paketin içindeki tüm paketler için kısa bir yardım metni basılır.
-n
--no-create
configure betiği normal olarak çalışır fakat herhangi bir çıktı dosyası üretmez. Derleme için Makefile dosyalarını üretmeksizin sınamaların sonuçlarını görmek için yararlıdır.
-q
--quiet
Yapılandırma sürecinde checking ... iletilerini basmaz.
--srcdir=dizin
dizin dizinini kaynak dosyaları dizini olarak tanımlar. configure betiğinin bulunduğu dizin veya bir üst dizin öntanımlıdır.
--silent
--quiet ile aynı.
-V
--version
Telif hakkı bilgilerini gösterir ve çıkar.

Kurulum dizinleri

Bu seçenekler kurulum dizinlerini tanımlar. Kurulum dizinleri seçilmiş yerleşime bağımlıdır.

--prefix=PREFIX
Mimariden bağımsız dosyalar PREFIX dizininin altına kurulur. /usr/local/apache2 öntanımlı kurulum dizinidir.
--exec-prefix=EPREFIX
Mimariye bağımlı dosyalar EPREFIX dizininin altına kurulur. Bunun için PREFIX dizini öntanımlı kurulum dizinidir.

Öntanımlı olarak, make install tüm dosyaların /usr/local/apache2/bin, /usr/local/apache2/lib gibi dizinlere kurulmasını sağlar. Kurulum dizini önekini örneğin, --prefix=$HOME şeklinde belirterek kurulumun başka bir yere yapılmasını sağlayabilirsiniz.

Bir dizin yerleşimi tanımlamak

--enable-layout=LAYOUT
Kaynak kodu ve derleme betikleri kurulum ağacının LAYOUT yerleşimine dayalı olduğu varsayımıyla yapılandırılır. Bu seçenek sayesinde Apache HTTP Sunucusu kurulumu içinde her dosya türü için farklı bir yer belirleyebilirsiniz. config.layout dosyasında böyle yapılandırma örnekleri vardır. Örnekleri izleyerek kendi yapılandırmanızı oluşturabilirsiniz. Bu dosyada örneğin FOO isimli yerleşim <Layout FOO>...</Layout> bölümü içinde düzenlenmiştir ve her yerleşim için böyle ayrı bir bölüm vardır. Öntanımlı yerleşim Apache’dir.

Kurulum dizinlerinde ince ayar

Kurulum dizinlerini daha iyi denetim altında tutmak için aşağıdaki seçenekler kullanılır. Lütfen, dizin öntanımlılarının autoconf tarafından tanımlandığına ve seçilen yerleşim ayarlarının bunları yerini aldığına dikkat ediniz.

--bindir=dizin
Kullanıcı tarafından çalıştırılabilen dosyalar dizin dizinine kurulur. Bunlar htpasswd, dbmmanage gibi site yönetimi için yararlı destek programlarıdır. Öntanımlı olarak bu dosyalar EPREFIX/bin dizinine kurulur.
--datadir=dizin
Mimariden bağımsız salt okunur veriler dizin dizinine kurulur. Bunların öntanımlı kurulum dizini PREFIX/share dizinidir. Bu seçenek autoconf tarafından atanır ve şimdilik kullanılmamıştır.
--includedir=dizin
C başlık dosyaları dizin dizinine kurulur. Bunların öntanımlı kurulum dizini PREFIX/include dizinidir.
--infodir=dizin
Info belgeleri dizin dizinine kurulur. Bunların öntanımlı kurulum dizini PREFIX/info dizinidir. Bu seçenek şimdilik kullanılmamıştır.
--libdir=dizin
Nesne kod kütüphaneleri dizin dizinine kurulur. Bunların öntanımlı kurulum dizini PREFIX/lib dizinidir.
--libexecdir=dizin
Paylaşımlı modüller gibi program dosyaları dizin dizinine kurulur. Öntanımlı olarak libexecdir bu dizini EPREFIX/modules olarak tanımlar.
--localstatedir=dizin
Düzenlenebilir tek makinelik veri dizin dizinine kurulur. Öntanımlı olarak localstatedir bu dizini PREFIX/var olarak tanımlar. Bu seçenek autoconf tarafından atanır ve şimdilik kullanılmamıştır.
--mandir=dizin
Kılavuz sayfaları dizin dizinine kurulur. Öntanımlı olarak mandir bu dizini EPREFIX/man olarak tanımlar.
--oldincludedir=dizin
GCC harici C başlık dosyaları dizin dizinine kurulur. Öntanımlı olarak oldincludedir bu dizini /usr/include olarak tanımlar. Bu seçenek autoconf tarafından atanır ve şimdilik kullanılmamıştır.
--sbindir=dizin
Sistem yöneticisi tarafından kullanılabilen programlar dizin dizinine kurulur. Bunlar httpd, apachectl, suexec gibi Apache HTTP Sunucusunu çalıştırmak için gereken programlardır. Öntanımlı olarak sbindir bu dizini EPREFIX/sbin olarak tanımlar.
--sharedstatedir=dizin
Mimariye bağımlı düzenlenebilir veriler dizin dizinine kurulur. Öntanımlı olarak sharedstatedir bu dizini PREFIX/com olarak tanımlar. Bu seçenek autoconf tarafından atanır ve şimdilik kullanılmamıştır.
--sysconfdir=dizin
httpd.conf, mime.types gibi tek makinelik salt okunur sunucu yapılandırma dosyaları dizin dizinine kurulur. Öntanımlı olarak sysconfdir bu dizini PREFIX/conf olarak tanımlar.

Sistem türleri

Bu seçenekleri Apache HTTP Sunucusunu başka bir platformda çalıştırmak üzere çapraz derleme yaparken kullanılır. Normal durumlarda sunucu derlendiği platformda çalıştırıldığından bu seçenekler kullanılmaz.

--build=derleme-ortamı
Derleme araçlarının derleneceği sistemin sistem türünü tanımlar. config.guess betiği ile elde edilen sonuç öntanımlıdır.
--host=çalışma-ortamı
Sunucunun çalışacağı sistemin sistem türünü tanımlar. Öntanımlı sistem türü derleme-ortamı’dır.
--target=hedef-ortam
Derleyicileri hedef-ortam sistem türü için yapılandırır. Öntanımlı sistem türü çalışma-ortamı’dır. Bu seçenek autoconf tarafından atanır ve Apache HTTP Sunucusu için gerekli değildir.

Seçimlik özellikler

Bu seçenekler HTTP sunucunuzun sahip olmasını istediğiniz özelliklerin hassas olarak ayarlanmasını sağlar.

Genel sözdizimi

Bir özelliği etkin kılmak veya iptal etmek için genellikle şu sözdizimi kullanılır:

--disable-özellik
Sunucu özellik özelliğine sahip olmaz. Bu seçenek--enable-özellik=no seçeneğine eşdeğerdir.
--enable-özellik[=değer]
Sunucu özellik özelliğine sahip olur. değer belirtilmediği takdirde yes (evet) öntanımlıdır.
--enable-modül=shared
Belirtilen modül DSO modülü olarak derlenir. Öntanımlı olarak etkin modüller devingen ilintilenir.
--enable-modül=static
Belirtilen modül durağan ilintilenir.

Bilginize

--enable-filanca seçeneğinin varlığı configure betiğinin filanca diye bir modül var olmasa bile bundan şikayetçi olmasına sebep olmaz. Bu bakımdan dikkatli olunuz.

Derlenecek modüllerin seçimi

Modüllerin çoğu öntanımlı olarak derlenir ve ya açıkça iptal edilmek ya da few veya none anahtar sözcükleri kullanılarak kaldırılmak zorunda kalınır (ayrıntılar için --enable-modules, --enable-mods-shared ve --enable-mods-static seçeneklerine bakın).

Öntanımlı olarak derlenmeyenler ise ya açıkça etkin kılınmak ya da all veya reallyall anahtar sözcükleriyle kullanılabilir yapılmak zorunda kalınır.

Hangi modüllerin öntanımlı olarak derlendiğini öğrenmek için ./configure -h veya ./configure --help komutunu çalıştırın ve çıktıdaki Optional Features bölümüne bakın. Örnek olarak, mod_example1 ve mod_example2 modülleriyle ilgilendiğinizi varsayalım:

Optional Features:
  ...
  --disable-example1     example module 1
  --enable-example2      example module 2
  ...

Burada, mod_example1 öntanımlı olarak etkindir ve derlenmemesini istiyorsanız --disable-example1 seçeneğini kullanmalısınız. mod_example2 ise öntanımlı olarak derlenmemektedir ve derlenmesini istiyorsanız --enable-example2 seçeneğini kullanmalısınız.

Çok Süreçlilik Modülleri

Çok Süreçlilik Modülleri veya MPM'ler sunucunun temel davranışını belirler. Sunucuya yüklenebilecek azami MPM sayısı birdir. Kullanılabilecek modüller modül dizininde listelenmiştir.

MPM'ler devingen yükleme için DSO olarak derlenebileceği gibi sunucuyla duruk olarak da ilintilenebilir ve bunlar aşağıdaki seçeneklerle etkin kılınır:

--with-mpm=MPM

Sunucu için öntanımlı MPM'i seçer. MPM'ler DSO modülleri olarak derleniyorsa (bak --enable-mpms-shared), bu seçenek öntanımlı yapılandırma dosyasında yüklenecek MPM'i seçer. Aksi takdirde, sunucuyla duruk olarak ilintilenecek, kullanılabilir tek MPM'i seçer.

Bu seçenek belirtilmezse, işletim sisteminiz için öntanımlı olan MPM seçilir.

--enable-mpms-shared=MPM-LISTESİ

MPM'leri devingen paylaşımlı modül olarak etkinleştirir. LoadModule yönergesi kullanılarak bu modüllerden biri devingen olarak yüklenmelidir.

MPM-LISTESİ MPM'lerin aralarına boşluk bırakılarak ve tamamı tek tırnaklarla sarmalanarak oluşturulmuş bir listesidir. Örnek:

--enable-mpms-shared='prefork worker'

Ek olarak, kullandığınız platformda devingen yüklemeyi destekleyen ve DSO modülü olarak derlenmiş tüm modülleri seçmek için all anahtar sözcüğünü de kullanabilirsiniz. Örnek:

--enable-mpms-shared=all

Üçüncü parti modüller

Üçüncü parti modülleri etkin kılmak için şu seçenekler kullanılır:

--with-module=modül-türü:modül-dosyası[,modül-türü:modül-dosyası]

Durağan ilintili modüller listesine belirtilen modülleri ekler. Modül kaynak dosyası modül-dosyası, önce Apache HTTP Sunucusu kaynak ağacı altında modules/modül-türü alt dizininde aranır. Modül orada değilse configure betiği modül-dosyası ile bir mutlak dosya yolu belirtildiği varsayımıyla kaynak dosyasını modül-türü alt dizinine kopyalamaya çalışır. Alt dizin mevcut değilse oluşturulur ve içine standart bir Makefile.in yerleştirilir.

Bu seçenek tek kaynak dosyasından oluşan küçük harici modülleri eklemek için yararlıdır. Daha karmaşık modüller için modül üreticisi tarafından sağlanan belgelere bakınız.

Bilginize

Durağan ilintili modüller yerine bir DSO modülü derlemek isterseniz apxs programını kullanınız.

Kümeleme seçenekleri ve diğerleri

--enable-maintainer-mode
Hata ayıklama iletileri ve derleme sırasındaki uyarıların gösterilmesi etkin kılınır ve derlenmiş tüm modüller yüklenir.
--enable-mods-shared=modül-listesi

Etkinleştirilip devingen paylaşımlı modül olarak derlenecek modüllerin listesi belirtilir. Yani, bu modüller LoadModule yönergesi kullanılarak devingen olarak yüklenir.

modül-listesi tırnak içine alınmış boşluk ayraçlı modül isimleri listesidir. Modül isimleri önlerindeki mod_ öneki olmaksızın belirtilirler. Örnek:

--enable-mods-shared='headers rewrite dav'

modül-listesi yerine reallyall, all, most, few ve none anahtar sözcükleri de belirtilebilir. Örneğin,

--enable-mods-shared=most

seçeneği ile çoğu modül DSO modülü olarak derlenir,

--enable-mods-shared=few

seçeneği ile sadece en temel modüller derlenir.

most öntanımlıdır.

Seçilen modüller için LoadModule yönergeleri ana yapılandırma dosyasında kendiliğinden üretilir. Öntanımlı olarak, --enable-foo yapılandıma seçeneği ile açıkça seçilen modüller ve gerekli olanlar dışında kalan LoadModule yönergeleri açıklama haline getirilir. Yüklü modülleri httpd.conf dosyasındaki LoadModule yönergelerini etkin kılarak veya açıklama haline getirerek değiştirebilirsiniz. LoadModule yönergelerine ek olarak, derlenmiş tüm modüller --enable-load-all-modules yapılandırma seçeneği ile de etkinleştirilebilir.

--enable-mods-static=modül-listesi
Bu seçenek modülleri devingen değil de durağan ilintilemek dışında --enable-mods-shared seçeneğine benzer. Yani bu modüller httpd çalıştırılır çalıştırılmaz etkin olurlar. Yüklenmeleri için LoadModule yönergesine ihtiyaçları yoktur.
--enable-modules=MODULE-LIST
Bu seçenek --enable-mods-shared gibi davranır ve ek olarak belirtilen modülleri devingen olarak ilintiler.Özel none anahtar sözcüğü tüm modüllerin derlenmesini iptal eder.
--enable-v4-mapped
IPv6 soketlierinin IPv4 bağlantılar üzerinde kullanılması mümkün olur.
--with-port=port
Bu seçenek httpd'nin dinleyeceği portu belirler. Bu port httpd.conf yapılandırma dosyası üretilirken kullanılır. 80. port öntanımlıdır.
--with-program-name
Öntanımlı olan httpd yerine başka bir çalıştırabilir ismi tanımlar.

Seçimlik paketler

Buradaki seçenekler seçimlik paketleri tanımlamak için kullanılır.

Genel sözdizimi

Bir seçimlik paketi tanımlamak için genellikle şöyle bir sözdizimi kullanılır:

--with-paket[=değer]
paket paketi kullanılır. Öntanımlı değer yes’tir.
--without-paket
paket paketi kullanılmaz. Öntanımlı değer no’dur. Bu seçenek autoconf tarafından sağlanmıştır ve Apache HTTP Sunucusu için pek yararlı değildir.

Özel paketler

--with-apr=dizin|dosya
Apache Taşınabilir Arayüzü (APR) httpd kaynak paketinin bir parçası olup HTTP Sunucu ile birlikte derlenir. Eğer kendi kurulu APR’nizi kullanmak isterseniz bunu configure betiğine apr-config betiğinin yolunu belirterek ifade edebilirsiniz. Kurulu APR için bid dizin, dosya ismi veya mutlak dosya yolu belirtebilirsiniz. apr-config ya belirttiğiniz dizinde ya da bin alt dizininde bulunmalıdır.
--with-apr-util=dizin|dosya
Apache Taşınabilir Arayüzü Araçları (APU) httpd kaynak paketinin bir parçası olup HTTP Sunucu ile birlikte derlenir. Eğer kendi kurulu APU’nuzu kullanmak isterseniz bunu configure betiğine apu-config betiğinin yolunu belirterek ifade edebilirsiniz. Kurulu APR için bir dizin, dosya ismi veya mutlak dosya yolu belirtebilirsiniz. apr-config ya belirttiğiniz dizinde ya da bin alt dizininde bulunmalıdır.
--with-ssl=dizin
mod_ssl modülü etkinse configure betiği kurulu bir OpenSSL arayacaktır. Kendi SSL/TLS kurulumunuzun yolunu bu seçenekle belirtebilirsiniz.
--with-z=dizin
Yapılandırmanız gerektirdiği takdirde (örneğin, mod_deflate etkinse) configure betiği kurulu zlib kütüphanesinin yerini tespit etmeye çalışacaktır. Kendi sıkıştırma kütüphanenizin yerini bu seçenekle belirtebilirsiniz.

Apache HTTP Sunucusunun çeşitli bölümleri, mod_authn_dbm modülü ve mod_rewrite modülünün RewriteMap yönergesi bilgilere erişimi hızlandırmak için basit anahtar/değer veritabanları kullanırlar. SDBM, APU içinde mevcut olduğundan bu veritabanı her zaman kullanılabilir durumdadır. Eğer başka veritabanı türleri kullanmak isterseniz aşağıdaki seçeneklerle bunları etkin kılabilirsiniz:

--with-gdbm[=dizin-yolu]
Bir dizin-yolu belirtilmemişse configure betiği GNU DBM kurulumunun kütüphanelerini ve başlık dosyalarını bulunması olası yerlerde arar. Bir dizin-yolu belirtilmişse configure betiği kurulumun kütüphanelerini dizin-yolu/lib altında, başlık dosyalarını ise dizin-yolu/include altında arayacaktır. Bundan başka, başlık ve kütüphane dosyalarının bulundukları yerler iki nokta imi ile ayrılarak dizin-yolu olarak belirtilebilir.
--with-ndbm[=dizin-yolu]
New DBM kurulumunu araştırması dışında --with-gdbm seçeneği gibidir.
--with-berkeley-db[=dizin-yolu]
Berkeley DB kurulumunu araştırması dışında --with-gdbm seçeneği gibidir.

Bilginize

DBM seçenekleri APU tarafından sağlanmış olup onun yapılandırma betiğine aktarılır. Bu seçenekler --with-apr-util seçeneği ile tanımlanmış bir kurulu APU varsa kullanışlı olur.

HTTP sunucunuz ile birlikte birden fazla DBM gerçeklenimi kullanabilirsiniz. Kullanılacak DBM türünü her zaman çalışma anı yapılandırmanızla yapılandırabilirsiniz.

Destek programları için seçenekler

--enable-static-support
Destek programlarını durağan ilintili olarak derler. Yani çalıştırılabilirin kullandığı bütün kütüphaneler kodla bütünleştirilir. Bu seçenek belirtilmedikçe destek programları daima devingen ilintili olarak derlenir.
--enable-suexec
Çatallanan sürecin kullanıcı ve grup kimliklerinin değiştirilebilmesini sağlayan suexec programının kullanımını etkinleştirir. Sunucunuz üzerinde suid biti etkinleştirilmiş bir program çalıştırmanın sistem güvenliğinde yaratacağı sorunlar hakkında bir fikriniz yoksa bu seçeneği etkinleştirmeyin. suexec yapılandırma seçenekleri aşağıda açıklanmıştır.

Tek bir destek programını aşağıdaki seçenekleri kullanarak bir durağan ilintili çalıştırılabilir olarak derleyebilirsiniz:

--enable-static-ab
ab programının durağan ilintili sürümü derlenir.
--enable-static-checkgid
checkgid programının durağan ilintili sürümü derlenir.
--enable-static-htdbm
htdbm programının durağan ilintili sürümü derlenir.
--enable-static-htdigest
htdigest programının durağan ilintili sürümü derlenir.
--enable-static-htpasswd
htpasswd programının durağan ilintili sürümü derlenir.
--enable-static-logresolve
logresolve programının durağan ilintili sürümü derlenir.
--enable-static-rotatelogs
rotatelogs programının durağan ilintili sürümü derlenir.

suexec yapılandırma seçenekleri

Aşağıdaki seçeneklerle suexec programının davranışı hassas bir şekilde ayarlanabilir. Daha ayrıntılı bilgi için suEXEC yapılandırması ve kurulumuna bakınız.

--with-suexec-bin
Bu seçenek ile suexec çalıştırılabilirinin yeri belirtilir. Öntanımlı olarak --sbindir ile belirtilen dizine kurulur (Kurulum dizinlerinde ince ayar konusuna bakınız).
--with-suexec-caller
Bu seçenek ile suexec’i çalıştırabilecek kullanıcı belirtilir. Normalde httpd programını çalıştıran kullanıcı olmalıdır.
--with-suexec-docroot
Bu seçenek ile suexec'e erişebilecek çalıştırılabilirlerin altında bulunacağı dizin belirtilir. --datadir/htdocs öntanımlıdır.
--with-suexec-gidmin
suexec için hedef kullanıcı olmasına izin verilen en küçük grup kimliğini tanımlamak için kullanılır. 100 öntanımlıdır.
--with-suexec-logfile
suexec günlük dosyasının ismi belirtilir. Öntanımlı olarak bu dosyanın ismi suexec_log olup --logfiledir seçeneği ile belirtilen dizin altında bulunur.
--with-suexec-safepath
suexec tarafından çalıştırılacak süreçlerin çalıştırılabilirlerinin bulunabileceği dizinleri PATH ortam değişkenine tanımlamak için kullanılır. /usr/local/bin:/usr/bin:/bin öntanımlıdır.
--with-suexec-userdir
Bu seçenek, kullanıcı dizinleri altında suexec tarafından çalıştırılacak süreçlerin çalıştırılabilirlerinin bulunabileceği alt dizini tanımlar. suexec programını (mod_userdir tarafından sağlanan) kullanıcıya özel dizinlerde kullanmak istediğinizde bu gereklidir. public_html alt dizini öntanımlıdır.
--with-suexec-uidmin
suexec için hedef kullanıcı olmasına izin verilen en küçük kullanıcı kimliğini tanımlamak için kullanılır. 100 öntanımlıdır.
--with-suexec-umask
suexec tarafından çalıştırılacak süreçler için umask tanımlar. Sisteminiz için geçerli ayarlar öntanımlıdır.

Ortam Değişkenleri

configure betiğinin yerleri ve isimleri standartlara uygun olmayan kütüphaneleri ve programları bulmasını yardımcı olan veya configure betiği tarafından yapılan bazı seçimleri değiştirmenizi sağlayacak bazı ortam değişkenleri vardır.

CC
Bu değişkenle derleme sırasında kullanılacak C derleyici komutu tanımlanır.
CFLAGS
Bu değişkenle derleme sırasında kullanılacak C derleyici seçenekleri tanımlanır.
CPP
Bu değişkenle derleme sırasında kullanılacak C önişlemci komutu tanımlanır.
CPPFLAGS
C/C++ önişlemci seçenekleri tanımlanır. Örneğin, eğer başlık dosyaları standart yerlerinde değil de includedir dizinindeyse bunu -Iincludedir seçeneği olarak belirtebilirsiniz.
LDFLAGS
İlintileyici seçenekleri tanımlanır. Örneğin, eğer kütüphane dosyalarınız standart yerlerinde değil de libdir dizinindeyse bunu -Llibdir seçeneği olarak belirtebilirsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


dbmmanage - DBM biçemli kullanıcı kimlik doğrulama dosyalarını yönetir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

dbmmanage - DBM biçemli kullanıcı kimlik doğrulama dosyalarını yönetir

dbmmanage, mod_authn_dbm üzerinden HTTP kullanıcılarının temel kimlik doğrulaması için kullanıcı isimlerinin ve parolalarının saklanmasında kullanılacak DBM dosyalarını oluşturmak ve güncellemek için kullanılır. Apache HTTP sunucusunun mevcut özkaynaklarının kullanımı sadece dbmmanage tarafından oluşturulan dosyalarda listelenmiş kullanıcılara tahsis edilebilir. Bu program sadece, kullanıcı isimleri bir DBM dosyasında saklanmak istenirse işe yarar. Düz metin bir veritabanı kullanmak isterseniz htpasswd sayfasına bakınız.

DBM parola veritabanı sağlayan diğer bir araç da htdbm'dir.

Bu kılavuz sayfası sadece komut satırı değiştirgelerini listeler. Kullanıcı kimlik doğrulamasını httpd'de yapılandırmak için gerekli yönergelerle ilgili ayrıntılar için Apache dağıtımının bir parçası olan ve http://httpd.apache.org/ adresinde de bulunan Apache HTTP Sunucusu Belgelerine bakınız.

Ayrıca bakınız:

  • httpd
  • htdbm
  • mod_authn_dbm
  • mod_authz_dbm

Kullanım

dbmmanage [ kodlama ] dosyaismi add|adduser|check|delete|update kullanıcı [ şifreli_parola [ grup[,grup...] [ açıklama ] ] ]

dbmmanage dosyaismi view [ kullanıcı ]

dbmmanage dosyaismi import

Seçenekler

dosyaismi
DBM dosyasının ismi. Genellikle, .db, .pag veya .dir eklentisi olmaksızın belirtilir.
kullanıcı
İşlemleri gerçekleştirecek kullanıcı ismi. kullanıcı ismi ikinokta imi (:) içeremez.
şifreli_parola
update ve add komutları için kullanılacak şifreli paroladır. Parolanın istenmesini sağlamak, fakat hemen ardından alanları doldurmak için bir tire imi (-) kullanabilirsiniz. Buna ek olarak, update komutunu kullanırken özgün parolaya dokunulmaması için bir nokta imi (.) kullanabilirsiniz.
grup
Kullanıcının üyesi olduğu grup. Grup ismi ikinokta imi (:) içeremez.Kullanıcıyı bir gruba atamadan açıklama alanını doldurmak istiyorsanız bir tire imi (-) kullanabilirsiniz. Buna ek olarak, update komutunu kullanırken özgün gruba dokunulmaması için bir nokta imi (.) kullanabilirsiniz.
açıklama
Adı ve soyadı, eposta adresi gibi kullanıcıyla ilgili bir takım bilgiler buraya yazılır. Sunucu bu alanı gözardı eder.

Kodlamalar

-d
CRYPT şifrelemesi (Win32 ve Netware hariç, öntanımlı)
-m
MD5 şifrelemesi (Win32 ve Netware için öntanımlı)
-s
SHA1 şifrelemesi
-p
düz metin (önerilmez)

Komutlar

add
şifreli_parola'yı kullanarak dosyaismi dosyasına kullanıcı için bir girdi ekler.

dbmmanage passwords.dat add rbowen foKntnEF3KSXA

adduser
Parola sorduktan sonra dosyaismi dosyasına kullanıcı için bir girdi ekler.

dbmmanage passwords.dat adduser krietz

check
Parola sorduktan sonra belirtilen kullanıcı, dosyaismi dosyasında var mı diye bakar; varsa belirtilen parolayı kullanıcınınkiyle eşleştirmeye çalışır.

dbmmanage passwords.dat check rbowen

delete
dosyaismi dosyasından kullanıcı girdisini siler.

dbmmanage passwords.dat delete rbowen

import
Standart girdiden kullanıcı:parola satırlarını (her satırda bir tane) okur ve bunları dosyaismi dosyasına ekler. Parola şifrelenmiş olmalıdır.
update
Belirtilen kullanıcı'nın dosyaismi dosyasında mevcut olması dışında adduser komutu gibidir.

dbmmanage passwords.dat update rbowen

view
Sadece, DBM dosyasının içeriğini gösterir. Bir kullanıcı belirtirseniz sadece o kaydı gösterir.

dbmmanage passwords.dat view

Hatalar

Birden fazla DBM dosya biçemi vardır ve büyük bir olasılıkla da sisteminizde bu birden fazla biçemle ilgili kütüphaneler vardır. SDBM, NDBM, GNU'nun GDBM projesi ve Berkeley DB 2 bunların başlıcalarıdır. Ne yazık ki, bu kütüphanelerin her birinin dosya biçimleri farklıdır. Bu bakımdan, dosyaismi dosyasında kullanılan dosya biçeminin dbmmanage tarafından kullanılanla aynı biçemde olduğundan emin olmalısınız. dbmmanage hangi tür DBM dosyasına baktığını saptayacak yeterliliğe sahip değildir. Yanlış biçemli bir dosya belirtirseniz hiçbir şey dönmeyebileceği gibi, başka isimde bir DBM dosyasının oluşturulması veya daha da kötüsü üzerine yazmaya çalışıyorsanız DBM dosyasının bozulması bile olasıdır.

dbmmanage programının başlangıcında @AnyDBM::ISA dizisi olarak tanımlanmış DBM biçem tercihlerinin bir listesi vardır. Berkeley DB 2 biçemini tercih ettiğimizden dbmmanage sistem kütüphanelerini şu sıraya göre arar: Berkeley DB 2, NDBM, GDBM ve SDBM. dbmmanage DBM dosyası hareketleri için bu sıralamaya göre bulduğu ilk kütüphaneyi kullanacaktır. Sıralama Perl'deki dbmopen() çağrısının kullandığından faklı olduğu gibi Perl'deki standart @AnyDBM::ISA sıralamasından da oldukça farklıdır. Bu bakımdan, DBM dosyalarınızı yönetmek için Perl ile yazılmış başka araçlar kullanıyorsanız, onların da bu tercih sırasını izlemesini sağlamalısınız. Benzer şekilde, bu dosyalara erişmek için diğer dillerde (C gibi) yazılmış programlar kullanıyorsanız bunlar için de aynı durum geçerlidir.

Unix sistemlerinde, kullanılan DBM dosyasının biçemini öğrenmek için file programı kullanılabilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


fcgistarter - Bir FastCGI programını çalıştır - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

fcgistarter - Bir FastCGI programını çalıştır

Ayrıca bakınız:

  • mod_proxy_fcgi

Bilginize

Şimdilik sadece Unix sistemlerinde çalışmaktadır.

Kullanım

fcgistarter -c komut -p port [ -i arabirim ] -N sayı

Seçenekler

-c komut
Çalıştırılacak FastCGI programı
-p port
Programın dinleyeceği port
-i arabirim
Programın dinleyeceği arabirim
-N sayı
Program örneklerinin sayısı

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


htcacheclean - Disk arabelleğini temizler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

htcacheclean - Disk arabelleğini temizler

htcacheclean, mod_cache_disk deposunun boyutlarını belli sınırlar içinde veya kullanımdaki dosya düğümlerinin sınırları içinde tutmak için kullanılır. Bu araç ya elle ya da bir artalan süreci olarak çalıştırılır. Artalan süreci olarak çalıştırıldığında, silinecek arabellek içeriğini tespit etmek için arabellek dizinlerine belli aralıklarla bakmak dışında uykuda olur. Artalan sürecini temiz olarak durdurmak için TERM veya INT sinyali göndermeniz yeterlidir. Elle çalıştırıldığında, silinecek arabellek içeriğini tespit etmek için arabellek dizinlerine bir kereliğine bakar. Bir veya daha fazla URL belirtilmesi durumunda arabellekte olanlar arabellekten silinir.

Ayrıca bakınız:

  • mod_cache_disk

Kullanım

htcacheclean
    [ -D ]
    [ -v ]
    [ -t ]
    [ -r ]
    [ -n ]
    [ -Rboyut ]
    -pyol
    [ -lsınır |
    -Llimit ]

htcacheclean [ -n ] [ -t ] [ -i ] [ -Ppiddosyası ] [ -Rboyut ] -dsüre -pyol [ -lsınır | -Llimit ]

htcacheclean [ -v ] [ -Rboyut ] -pyol [ -a ] [ -A ]

htcacheclean [ -D ] [ -v ] [ -t ] [ -Rboyut ] -pyol url

Seçenekler

-d süre
Artalanda çalışarak süre dakikada bir arabelleği temizler. Bu seçenek -D, -v ve -r seçenekleri ile birlikte kullanılamaz. Artalan sürecini temiz olarak sonlandırmak için SIGTERM veya SIGINT göndermek yeterlidir.
-D
Kuru kuruya çalışıp, hiçbir şeyi silmez. -d seçeneği ile birlikte kullanılamaz. Kuru çalıştırma sırasında -t seçeneği ile dizinler silinmek istenirse, statlarda silinmiş görünen dosya düğümleri silinmiş dizinler olarak hesaba katılmaz ve tahmini olarak imlenir.
-v
Çıktı daha ayrıntılı olur. -d seçeneği ile birlikte kullanılamaz.
-r
İyice temizlik yapılır. Bunun için Apache HTTP sunucusunun çalışmadığı varsayılır (aksi takdirde arabellek içeriği bozulabilir). -t seçeneğinin de uygulanmasını sağlar. -d seçeneği ile birlikte kullanılamaz.
-n
Nazik olur. Diğer süreçlerin yararına daha yavaş çalışır. (a) disk G/Ç işlemlerinde gecikmeler olursa ve (b) çekirdek bu arada başka bir süreci öne çekmişse htcacheclean uyumayı tercih edecektir.
-t
Tüm boş dizinleri siler. Öntanımlı olarak, sadece arabellek dosyaları silinirse de bazı yapılandırmalarda büyük miktarda dizin oluşturulması bu seçeneğin kullanılmasını gerektirebilir. Yapılandırmanız çok sayıda dizin gerektiriyorsa ve dosya düğümlerinin veya dosya ayırma tablolarının tükenmesi sözkonusu ise bu seçeneğin kullanılması önerilir.
-p yol
yol, disk arabelleğinin kök dizini olarak belirtilir. CacheRoot yönergesinde belirtilen dizin olmalıdır.
-Ppiddosyası
Artalan süreci olarak çalışmada süreç kimliğinin yazılacağı dosyanın adını belirtmek için kullanılır.
-Rboyut
Disk bloklarının boyunu denkleştirmek için yuvarlanacak üst boyutu belirtmekte kullanılır. Arabellek bölümünün blok boyutunu belirler.
-l sınır
sınır, disk arabelleğinin toplam boyutu olarak belirtilir. Değerin öntanımlı olarak bayt cinsinden belirtileceği varsayılır. Değerin sonuna kilobayt için K, megabayt M, bayt için B harfi konulabilir.
-Llimit
Disk arabellek dosyası düğümü toplamının sınırını belirlemekte kullanılır.
-i
Akıllı olup sadece disk arabelleği değiştiği zaman çalışır. Bu seçenek -d seçeneği ile birlikte belirtilmek zorundadır.
-a
O an arabellekte saklanmakta olan URL'leri listeler. Birden fazla aynı URL varsa yalnız biri listelenir.
-A
O an arabellekte saklanmakta olan URL'leri öznitelikleri ile listeler. Öznitelikler şu sırayla verilir: url, header size, body size, status, entity version, date, expiry, request time, response time, body present, head request

Belli bir URL'nin silinmesi

htcacheclean tarafından aktarılan URL'ler arabellekten silinir. Bir URL birden fazla mevcutsa hepsi silinir.

Ters vekilli bir URL silinmişse, etkin URL Host başlığı port, yol ve sorgu ile oluşturulur. Bir sorgu dizgesi olsun olmasın, URL içinde '?' daima açıkça belirtilmelidir. Örneğin, localhost sunucusundaki / yolu silinmek istenirse silinecek URL http://localhost:80/? olurdu.

Arabellekteki URL'lerin listelenmesi

htcacheclean'e -a veya -A seçeneğinin aktarılmasıyla, arabellekteki URL'ler bulundukça her satıra bir URL gelecek biçemde listelenir. -A seçeneği URL'nin ardından arabellek içeriğini tamamını şu sırayla dökümler:

url
Öğenin URL'si.
header size
Bayt cinsinden başlık uzunluğu.
body size
Bayt cinsinden gövde uzunluğu.
status
Arabellekteki yanıtın durumu.
entity version
Öğenin silinmeksizin kaç kere doğrulandığı.
date
Yanıt tarihi.
expiry
Yanıtın zaman aşımı tarihi.
request time
İsteğin başlama zamanı.
response time
İsteğin bitiş zamanı.
body present
0 ise istekle birlikte gövde saklanmaz, 1 ise saklanır.
head request
1 ise, öğe, gövde olmaksızın arabellekli bir HEAD isteği içerir, 0 ise içermez.

Çıkış Durumu

htcacheclean, tüm işlemler başarıyla yerine getirildiğinde 0, aksi takdirde 1 döndürür. Bir URL belirtildiğinde, bu URL arablleklenmi ve silinmişse 0, aksi takdirde 2 döndürür. URL'nin silinmesi sırasında bir hata oluşursa 1 döndürür.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


htdbm - DBM parola veritabanlarını yönetir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

htdbm - DBM parola veritabanlarını yönetir

htdbm, mod_authn_dbm üzerinden HTTP kullanıcılarının temel kimlik doğrulaması için kullanıcı isimlerinin ve parolalarının saklanmasında kullanılacak DBM dosyalarını yönetmek için kullanılır. DBM dosyaları hakkında daha ayrıntılı bilgi edinmek için dbmmanage sayfasına bakınız.

Ayrıca bakınız:

  • httpd
  • dbmmanage
  • mod_authn_dbm

Kullanım

htdbm [ -TVTtürü ] [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] parola-dosyası kullanıcı

htdbm -b [ -TVTtürü ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] parola-dosyası kullanıcı parola

htdbm -n [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] kullanıcı

htdbm -nb [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] kullanıcı parola

htdbm -v [ -TVTtürü ] [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] parola-dosyası kullanıcı

htdbm -vb [ -TVTtürü ] [ -c ] [ -m | -B -d | -s | -p ] [ -C bedel ] [ -t ] [ -v ] parola-dosyası kullanıcı parola

htdbm -x [ -TVTtürü ] parola-dosyası kullanıcı

htdbm -l [ -TVTtürü ]

Seçenekler

-b
Betik kipi; parola için istek yapmak yerine parola komut satırından verilir. Parola komut satırında görünür olacağından çok dikkatli kullanmak gerekir. Betik kullanımı için -i seçeneğine bakınız.
-i
Parolayı doğrulamaksızın standart girdiden okur (betik kullanımı için).
-c
parola-dosyası oluşturur. Dosya mevcutsa, dosya silinip yeniden yazılır. Bu seçenek -n seçeneği ile birlikte kullanılamaz.
-n
Sonuçları veritabanında güncellemek yerine standart çıktıya gönderir. parola-dosyası belirtilmediğinden, bu seçenek komut satırı sözdizimini değiştirir. Bu seçenek -c seçeneği ile birlikte kullanılamaz.
-m
Parolalar için MD5 şifrelemesi kullanılır. Windows ve Netware için bu öntanımlıdır.
-B
Parolalar için bcrypt şifrelemesi kullanılır. Şu an için çok güvenli kabul edilmektedir.
-C bedel
Bu seçenek sadece -B (bcrypt şifrelemesi) seçeneği ile birlikte kullanılabilir. Bcrypt algoritmasına hesaplama süresini belirtir (daha yüksek değerler daha güvenlidir, öntanımlı 5, geçerli değerler: 4 - 31).
-d
Parolaları şifrelemek için crypt() kullanılır. Windows, ve Netware dışında öntanımlıdır. htdbm tarafından tüm platformlarda destekleniyor olsa da Windows ve Netware üzerinde httpd sunucusu tarafından desteklenmez. Bu algoritma günümüz standartlarında güvenilmez kabul edilmektedir.
-s
Parolalar için SHA şifrelemesi kullanılır. LDAP Dizin değişim biçemini (ldif) kullanarak Netscape sunucularına/sunucularından göçü kolaylaştırır. Bu algoritma günümüz standartlarında güvenilmez kabul edilmektedir.
-p
Düz metin parolalar kullanılır. htdbm tarafından tüm platformlarda destekleniyor olsa da Windows, Netware ve TPF üzerinde httpd sunucusu tarafından sadece düz metin parolalar kabul edilir.
-l
Veritabanındaki kullanıcıları açıklamalarıyla birlikte standart çıktıya gönderir.
-v
Kullanıcı adını ve parolasını doğrular. Program belirtilen parolanın geçerli olup olmadığını belirten bir ileti basar. Eğer parola geçersizse program hata kodu 3 ile çıkar.
-x
Kullanıcıyı siler. Kullanıcı belirtilen DBM dosyasında mevcutsa silinir.
-t
Son değiştirgenin bir açıklama olarak yorumlanmasını sağlar. Bu seçenek kullanıldığında komut satırının sonuna fazladan bir dizge eklenebilir. Bu dizge, veritabanında belirtilen kullanıcının "Comment" alanında saklanır.
parola-dosyası
DBM dosyasının ismi. Genellikle, .db, .pag veya .dir eklentisi olmaksızın belirtilir. -c seçeneği ile birlikte verilmişse ve DBM dosyası mevcut değilse dosya oluşturulur, mevcutsa dosya güncellenir.
kullanıcı
parola-dosyası'nda oluşturulacak veya güncellenecek kullanıcı ismi. kullanıcı bu dosyada mevcut değilse yeni bir girdi eklenir. Girdi mevcutsa parolası değiştirilir.
parola
Şifrelenip DBM dosyasında saklanacak düz metin parola. Sadece -b seçeneği ile kullanılır.
-T VTtürü
DBM dosyasının türü; SDBM, GDBM, DB, veya "default" olabilir.

Hatalar

Birden fazla DBM dosya biçemi vardır ve büyük bir olasılıkla da sisteminizde bu birden fazla biçemle ilgili kütüphaneler vardır. SDBM, NDBM, GNU'nun GDBM projesi ve Berkeley/Sleepycat DB 2/3/4 bunların başlıcalarıdır. Ne yazık ki, bu kütüphanelerin her birinin dosya biçimleri farklıdır. Bu bakımdan, dosyaismi dosyasında kullanılan dosya biçeminin htdbm tarafından kullanılanla aynı biçemde olduğundan emin olmalısınız. htdbm hangi tür DBM dosyasına baktığını saptayacak yeterliliğe sahip değildir. Yanlış biçemli bir dosya belirtirseniz hiçbir şey dönmeyebileceği gibi, başka isimde bir DBM dosyasının oluşturulması veya daha da kötüsü üzerine yazmaya çalışıyorsanız DBM dosyasının bozulması bile olasıdır.

Unix sistemlerinde, kullanılan DBM dosyasının biçemini öğrenmek için file programı kullanılabilir.

Çıkış Durumu

htdbm, kullanıcı ismi ve parolasını DBM dosyasına başarıyla eklemiş veya güncellemişse 0, dosyalara erişirken bir sorun çıkmışsa 1, komut satırında bir sözdizimi hatası varsa 2, parola etkileşimli alınmış fakat girdi ile eşleşme sağlanamamışsa 3, işlem kesintiye uğramışsa 4, bir değer çok uzunsa 5 (kullanıcı, parola, dosya ismi veya açıklama), kullanıcı ismi kuraldışı karakter içeriyorsa (Kısıtlamalar bölümüne bakınız) 6 ve dosya geçerli bir DBM parola dosyası değilse 7 değeriyle döner.

Örnekler

htdbm /usr/local/etc/apache/.htdbm-users jsmith

jsmith kullanıcısı için parolayı ekler veya değiştirir. Parolayı vermesi için kullanıcıya parola isteği yapılır. Windows üzerinde çalıştırılırsa parola Apache MD5 algoritması ile şifrelenir, aksi takdirde sistemin crypt() yordamı kullanılır. Dosya mevcut değilse htdbm beklenen hiçbir işlemi yapmadan bir hata vererek çıkar.

htdbm -c /home/doe/public_html/.htdbm jane

Yeni bir dosya oluşturur ve kullanıcı jane için kaydı bir girdi olarak bu dosyaya yazar. Dosya mevcutsa fakat okunamıyor veya yazılamıyorsa dosyada bir değişiklik yapılmaz ve htdbm bir ileti gösterip bir hata durumu ile çıkar.

htdbm -mb /usr/web/.htdbm-all jones Pwd4Steve

Komut satırından verilen parolayı (Pwd4Steve) MD5 algoritmasıyla şifreler ve bunu belirtilen dosyada saklar.

Güvenlik Değerlendirmeleri

htdbm tarafından yönetilen parola dosyalarına sunucunun URI uzayından erişilememelidir; yani dosya bir tarayıcı ile okunabilecek bir yerde bulunmamalıdır.

Komut satırında parolanın şifrelenmemiş olarak görünmesi sebebiyle -b seçeneğinin kullanımından kaçınılmasını öneriyoruz.

crypt() algoritması kullanılırken, parolayı şekillendirmek için parolanın ilk 8 baytının kullanılacağına dikkat ediniz. Eğer parola 8 bayttan uzunsa kalanlar bir uyarı verilmeksizin iptal edilir.

SHA şifreleme biçeminde tuz kullanılmaz; yani, bir parolanın sadece bir şifreli gösterimi olabilir. crypt() ve MD5 biçemleri parolanın önüne rasgele üretilmiş bir tuz dizgesi eklediklerinden sözlük saldırılarına karşı daha dayanıklıdır.

SHA ve crypt() biçimleri günümüz standartlarında güvenilmez kabul edilmektedir.

Kısıtlamalar

Windows platformunda, htdbm ile şifrelenen parolalar 255 karakterden daha uzun olamaz. 255 karakterden sonrası kırpılır.

htdbm tarafından kullanılan MD5 algoritması Apache yazılımına özeldir; bu algoritma ile şifrelenen parolalar başka HTTP sunucularında kullanılamayabilir.

Kullanıcı isimleri 255 bayttan uzun olamaz ve iki nokta imi (:) içeremez.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


htdigest - Özet kimlik doğrulama dosyalarını yönetir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

htdigest - Özet kimlik doğrulama dosyalarını yönetir

htdigest, HTTP kullanıcılarının digest türü kimlik doğrulaması için kullanıcı isimlerinin ve parolalarının saklanmasında kullanılacak düz metin dosyalarını oluşturmak ve güncellemek için kullanılır. Apache HTTP sunucusunun mevcut özkaynaklarının kullanımı sadece htdigest tarafından oluşturulan dosyalarda listelenmiş kullanıcılara tahsis edilebilir.

Bu kılavuz sayfası sadece komut satırı değiştirgelerini listeler. Kullanıcı kimlik doğrulamasını httpd'de yapılandırmak için gerekli yönergelerle ilgili ayrıntılar için Apache dağıtımının bir parçası olan ve http://httpd.apache.org/ adresinde de bulunan Apache HTTP Sunucusu Belgelerine bakınız.

Ayrıca bakınız:

  • httpd
  • mod_auth_digest

Kullanım

htdigest [ -c ] parola-dosyası bölge kullanıcı

Seçenekler

-c
parola-dosyası oluşturur. Dosya mevcutsa, dosya silinip yeniden yazılır.
parola-dosyası
Kullanıcı ismi, parola ve bölge bilgilerini içeren dosyanın ismi. -c seçeneği verilmişse ve dosya mevcut değilse oluşturulur, dosya mevcutsa silinip yeniden oluşturulur.
bölge
Kullanıcının mensup olduğu bölge ismi. Daha fazla bilgi için: http://tools.ietf.org/html/rfc2617#section-3.2.1
kullanıcı
parola-dosyası'nda oluşturulacak veya güncellenecek kullanıcı ismi. kullanıcı bu dosyada mevcut değilse yeni bir girdi eklenir. Girdi mevcutsa parolası değiştirilir.

Güvenlik Değerlendirmeleri

Bu program bir setuid çalıştırılabiliri olarak güvenilir olmadığından setuid yapılmamalıdır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


htpasswd - Temel kimlik doğrulama dosyalarını yönetir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

htpasswd - Temel kimlik doğrulama dosyalarını yönetir

htpasswd, HTTP kullanıcılarının temel kimlik doğrulaması için kullanıcı isimlerinin ve parolalarının saklanmasında kullanılacak düz metin dosyalarını oluşturmak ve güncellemek için kullanılır. htpasswd, güncelleme sırasında yazmak veya okumak için bir dosyaya erişemezse beklenen hiçbir işlemi yapmaz ve hata vererek çıkar.

Apache HTTP sunucusunun mevcut özkaynaklarının kullanımı sadece htpasswd tarafından oluşturulan dosyalarda listelenmiş kullanıcılara tahsis edilebilir. htpasswd sadece düz metin dosyalarda saklanmış kullanıcı isimlerini ve parolalarını yönetirse de, diğer veri saklama türleri için parolayı şifreleyip gösterebilir. Bir DBM veritabanı kullanmak isterseniz dbmmanage ve htdbm sayfasına bakınız.

htpasswd, parolaları şifrelemek için bcrypt, Apache'nin kendine özgü MD5 algoritması, SHA1 ya da sistemin crypt() yordamını kullanır. Bu bakımdan htpasswd tarafından yönetilen dosyalar farklı algoritmalarla şifrelenmiş parolalar içerebilir.

Bu kılavuz sayfası sadece komut satırı değiştirgelerini listeler. Kullanıcı kimlik doğrulamasını httpd'de yapılandırmak için gerekli yönergelerle ilgili ayrıntılar için Apache dağıtımının bir parçası olan ve http://httpd.apache.org/ adresinde de bulunan Apache HTTP Sunucusu Belgelerine bakınız.

Ayrıca bakınız:

  • httpd
  • htdbm
  • Kaynak paketinin support/SHA1 dizinindeki betikler.

Kullanım

htpasswd [ -c ] [ -i ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -D ] [ -v ] parola-dosyası kullanıcı

htpasswd -b [ -c ] [ -m | -B | -d | -s | -p ] [ -C bedel ] [ -D ] [ -v ] parola-dosyası kullanıcı parola

htpasswd -n [ -i ] [ -m | -B | -d | -s | -p ] [ -C bedel ] kullanıcı

htpasswd -nb [ -m | -B | -d | -s | -p ] [ -C bedel ] kullanıcı parola

Seçenekler

-b
Betik kipi; parola için istek yapmak yerine parola komut satırından verilir. Parola komut satırında görünür olacağından çok dikkatli kullanmak gerekir. Betik kullanımı için -i seçeneğine bakınız. 2.4.4 ve sonraki sürümler içindir.
-i
Parolayı doğrulamaksızın standart girdiden okur (betik kullanımı için).
-c
parola-dosyası oluşturur. Dosya mevcutsa, dosya silinip yeniden yazılır. Bu seçenek -n seçeneği ile birlikte kullanılamaz.
-n
Sonuçları veritabanında güncellemek yerine standart çıktıya gönderir. Bu seçenek, Apache'nin metin veriler içermeyen veri depolarına dahil edilebilecek parolaları üretmekte yararlıdır. parola-dosyası belirtilmediğinden, bu seçenek komut satırı sözdizimini değiştirir. Bu seçenek -c seçeneği ile birlikte kullanılamaz.
-m
Parolalar için MD5 şifrelemesi kullanılır. Bu 2.2.18 sürümünden beri öntanımlıdır.
-B
Parolalar için bcrypt şifrelemesi kullanılır. Şu an için çok güvenli kabul edilmektedir.
-C bedel
Bu seçenek sadece -B (bcrypt şifrelemesi) seçeneği ile birlikte kullanılabilir. Bcrypt algoritmasına hesaplama süresini belirtir (daha yüksek değerler daha güvenlidir, öntanımlı 5, geçerli değerler: 4 - 31).
-d
Parolaları şifrelemek için crypt() kullanılır. htpasswd tarafından tüm platformlarda destekleniyor olsa da Windows, Netware ve TPF üzerinde httpd sunucusu tarafından desteklenmez. Bu algoritma günümüz standartlarında güvenilmez kabul edilmektedir. 2.2.17 sürümüne kadar öntanımlı algoritma olarak kullanılmıştı.
-s
Parolalar için SHA şifrelemesi kullanılır. LDAP Dizin değişim biçemini (ldif) kullanarak Netscape sunucularına/sunucularından göçü kolaylaştırır.Bu algoritma günümüz standartlarında güvenilmez kabul edilmektedir.
-p
Düz metin parolalar kullanılır. htpasswd tarafından tüm platformlarda destekleniyor olsa da Windows, Netware ve TPF üzerinde httpd sunucusu tarafından sadece düz metin parolalar kabul edilir.
-D
Kullanıcıyı siler. Kullanıcı belirtilen dosyada mevcutsa silinir.
-v
Parolayı doğrular. Verilen parolayı belitilen htpasswd dosyasında saklanan kullanıcı parolası ile karşılaştırarak doğrulama yapar. 2.4.5 ve sonraki sürümler içindir.
parola-dosyası
Kullanıcı ismini ve parolasını içeren dosyanın ismi. -c seçeneği verilmişse ve dosya mevcut değilse oluşturulur, dosya mevcutsa silinip yeniden oluşturulur.
kullanıcı
parola-dosyası'nda oluşturulacak veya güncellenecek kullanıcı ismi. kullanıcı bu dosyada mevcut değilse yeni bir girdi eklenir. Girdi mevcutsa parolası değiştirilir.
parola
Şifrelenip dosyada saklanacak düz metin parola. Sadece -b seçeneği ile kullanılır.

Çıkış Durumu

htpasswd, kullanıcı ismi ve parolasını DBM dosyasına başarıyla eklemiş veya güncellemişse 0, dosyalara erişirken bir sorun çıkmışsa 1, komut satırında bir sözdizimi hatası varsa 2, parola etkileşimli alınmış fakat girdi ile eşleşme sağlanamamışsa 3, işlem kesintiye uğramışsa 4, bir değer çok uzunsa 5 (kullanıcı, parola, dosya ismi veya açıklama), kullanıcı ismi kuraldışı karakter içeriyorsa (Kısıtlamalar bölümüne bakınız) 6 ve dosya geçerli bir DBM parola dosyası değilse 7 değeriyle döner.

Örnekler

htpasswd /usr/local/etc/apache/.htpasswd-users jsmith

jsmith kullanıcısı için parolayı ekler veya değiştirir. Parolayı vermesi için kullanıcıya parola isteği yapılır. Parola takviyeli Apache MD5 algoritması ile şifrelenir. Dosya mevcut değilse htpasswd beklenen hiçbir işlemi yapmadan bir hata vererek çıkar.

htpasswd -c /home/doe/public_html/.htpasswd jane

Yeni bir dosya oluşturur ve kullanıcı jane için kaydı bir girdi olarak bu dosyaya yazar. Dosya mevcutsa fakat okunamıyor veya yazılamıyorsa dosyada bir değişiklik yapılmaz ve htpasswd bir ileti gösterip bir hata durumu ile çıkar.

htpasswd -db /usr/web/.htpasswd-all jones Pwd4Steve

Komut satırından verilen parolayı (Pwd4Steve) crypt() algoritmasıyla şifreler ve bunu belirtilen dosyada saklar.

Güvenlik Değerlendirmeleri

htpasswd tarafından yönetilen parola dosyalarına sunucunun URI uzayından erişilememelidir; yani dosya bir tarayıcı ile okunabilecek bir yerde bulunmamalıdır.

Bu program bir setuid çalıştırılabiliri olarak güvenilir olmadığından setuid yapılmamalıdır.

Komut satırında parolanın şifrelenmemiş olarak görünmesi sebebiyle -b seçeneğinin kullanımından kaçınılmasını öneriyoruz.

crypt() algoritması kullanılırken, parolayı şekillendirmek için parolanın ilk 8 baytının kullanılacağına dikkat ediniz. Eğer parola 8 bayttan uzunsa kalanlar bir uyarı verilmeksizin iptal edilir.

SHA şifreleme biçeminde tuz kullanılmaz; yani, bir parolanın sadece bir şifreli gösterimi olabilir. crypt() ve MD5 biçemleri parolanın önüne rasgele üretilmiş bir tuz dizgesi eklediklerinden sözlük saldırılarına karşı daha dayanıklıdırlar.

SHA ve crypt() biçimleri günümüz standartlarında güvenilmez kabul edilmektedir.

Kısıtlamalar

Windows platformuda, htpasswd ile şifrelenen parolalar 255 karakterden daha uzun olamaz. 255 karakterden sonrası kırpılır.

htpasswd tarafından kullanılan MD5 algoritması Apache yazılımına özeldir; bu algoritma ile şifrelenen parolalar başka HTTP sunucularında kullanılamayabilir.

Kullanıcı isimleri 255 bayttan uzun olamaz ve iki nokta imi (:) içeremez.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


httxt2dbm - RewriteMap ile kullanmak için DBM dosyaları üretir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

httxt2dbm - RewriteMap ile kullanmak için DBM dosyaları üretir

httxt2dbm, RewriteMap ile kullanmak için düz metin dosyalardan DBM dosyaları üretir.

Çıktı dosyası mevcutsa dosya kırpılmaz. Yeni anahtarlar eklenir, mevcutlar da güncellenir.

Ayrıca bakınız:

  • httpd
  • mod_rewrite

Kullanım

httxt2dbm [ -v ] [ -f DBM_türü ] -i kaynak_metin -o çıktı_DBM

Seçenekler

-v
Çıktı daha ayrıntılı olur.
-f DBM_türü
Çıktı için kullanılacak DBM türü belirtilir. Belirtilmediği takdirde APR öntanımlısı kullanılır. Belirtilebilecek DBM türleri: GDBM dosyalar için GDBM, SDBM dosyalar için SDBM, Berkeley DB dosyalar için DB, NDBM dosyalar için NDBM, öntanımlı DBM türü için default
-i kaynak_metin
DBM dosyasının üretiminde kullanılacak girdi dosyası belirtilir. Bu dosya, her satırda bir kayıt bulunmak üzere her satırı şöyle biçemlenmiş olmalıdır: anahtar değer. Bu dosyanın biçemi ve manası ile ilgili ayrıntılar için RewriteMap yönergesinin açıklamasına bakınız.
-o çıktı_DBM
Çıktılanacak DBM dosyasının ismi belirtilir.

Örnekler

httxt2dbm -i rewritemap.txt -o rewritemap.dbm
httxt2dbm -f SDBM -i rewritemap.txt -o rewritemap.dbm

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


logresolve - Apache günlük dosyalarındaki IP adreslerini konak isimlerine dönüştürür - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

logresolve - Apache günlük dosyalarındaki IP adreslerini konak isimlerine dönüştürür

logresolve, Apache'nin erişim günlüklerindeki IP adreslerini çözümlemek için bir ardıl işlem uygulamasıdır. İsim sunucunuza bindirdiği yükü en aza indirmek için logresolve kendi arabelleğinde oluşturduğu eşleme tablosunu kullanır.

Apache günlük dosyasını standart girdisinden okur. IP adresleri günlük dosyası satırlarında ilk bileşen olmalı ve sonraki bileşenlerden bir boşluk ile ayrılmalıdır.

Kullanım

logresolve [ -s dosyaismi ] [ -c ] < günlük_dosyası > yeni_günlük_dosyası

Seçenekler

-s dosyaismi
İstatistiklerin kaydedileceği dosyanın ismi belirtilir.
-c
logresolve uygulamasının bazı DNS sorguları yapmasına sebep olur: IP adresine karşılık olan konak ismini bulduktan sonra özgün adresle karşılaştırmak için bu konak ismine karşılık gelen IP adresini sorgular.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


log_server_status - Log periodic status summaries - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Programs

log_server_status - Log periodic status summaries

This perl script is designed to be run at a frequent interval by something like cron. It connects to the server and downloads the status information. It reformats the information to a single line and logs it to a file. Adjust the variables at the top of the script to specify the location of the resulting logfile. mod_status will need to be loaded and configured in order for this script to do its job.

Usage

The script contains the following section.

my $wherelog = "/usr/local/apache2/logs/";  # Logs will be like "/usr/local/apache2/logs/19960312"
my $server   = "localhost";        # Name of server, could be "www.foo.com"
my $port     = "80";               # Port on server
my $request = "/server-status/?auto";    # Request to send

You'll need to ensure that these variables have the correct values, and you'll need to have the /server-status handler configured at the location specified, and the specified log location needs to be writable by the user which will run the script.

Run the script periodically via cron to produce a daily log file, which can then be used for statistical analysis.


rotatelogs - Apache günlüklerini döndürmek için borulu günlük kayıt programı - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

rotatelogs - Apache günlüklerini döndürmek için borulu günlük kayıt programı

rotatelogs, Apache'nin borulu günlük dosyaları özelliği ile birlikte kullanmak için tasarlanmış basit bir programdır. Günlük dosyasının azami boyutuna göre veya belli aralıklarla günlük dosyalarını döndürür.

Kullanım

rotatelogs
     [ -l ]
     [ -L isim ]
     [ -p program ]
     [ -f ]
     [ -t ]
     [ -v ]
     [ -e ]
     [ -c ]
     [ -n dosya_sayısı ]
     dosyaismi
     süre|boyut(B|K|M|G)
     [ saat_farkı ]

Seçenekler

-l
GMT yerine yerel zamanın kullanılmasını sağlar.
-L bagismi
Belirtilen bağ dosyası ismine geçerli günlük dosyasından kalıcı bir bağ oluşturulur. tail -F bagismi gibi bir komut kullanılarak günlüğün sürekli izlenmesi için kullanılabilir.
-p program
Belirtildiği takdirde, rotatelogs yeni bir günlük dosyasının her açılışında belirtilen programı çalıştırır. Yeni açılan dosyanın ismi programa ilk argüman olarak aktarılır. Bu işlem bir döndürme sonrası yapılırsa eski günlük dosyası ikinci argüman olarak aktarılır. rotatelogs işlemini sürdürmek için belirtilen programın sonlanmasını beklemez, dolayısıyla sonlanma soucunda döndürülen hata kodunu günlüğe kaydetmez. Çalıştırılan program rotatelogs ile aynı stdin, stdout ve stderr'i kullanır ve ortamı da miras alır.
-f
İlk günlük giridisinin okunmasını beklemeden rotatelogs başlar başlamaz günlük dosyasının açılmasını sağlar. Çok meşgul sitelerde, sunucu başlatılıp ilk istek sunuluncaya kadar geçen zamanda günlük dosyasının yokluğu özdevinimli işlemler yapan bazı günlükleme araçlarında sorunlara yol açabilir. Bu seçenek bu gibi durumlarda yararlıdır.
-t
Günlük dosyasının döndürülmek yerine tepeden kırpılmasına sebep olur. Günlüğün tail gibi bir araç tarafından gerçek zamanda işlendiği ve veriyi saklamanın gerekmediği durumda kullanışlıdır. Dosya ismine bir sonek eklenmez, ancak biçem dizgesi '%' karakteri içeriyorsa buna uyulur.
-v
Standart hataya verilen çıktı daha ayrıntılı olur. Çıktı, yapılandırma çözümlemesinin sonuçlarını ve tüm dosya açma/kapama işlemlerini içerir.
-e
Günlüğü standart çıktıya basar. Günlüğün zincirdeki ilgili araç tarafından gerçek zamanda işlenmesi gerektiğinde kullanışlıdır.
-c
Create log file for each interval, even if empty.
-n dosya_sayısı
Zaman damgalarına bakılmaksızın bir dosya serisi açılır. Örneğin -n3 belirtilirse "logfile", "logfile.1", "logfile.2" serisi açılır ve "logfile" üzerine yazılır. 2.4.5 ve sonraki sürümler içindir.
dosyaismi

Günlük dosyasının ismi yoluyla birlikte belirtilir. dosyaismi '%' karakterleri içeriyorsa bunlar strftime(3) biçem belirteçleri olarak ele alınır. Aksi takdirde, özdevinimli olarak .nnnnnnnnnn uzantısı üretilir. (-t seçeneği kullanılmadıkça) Uzantı saniye cinsindendir ve her iki durumda da bu değer, mevcut döngü diliminin başlangıcına göre hesaplanır. Örneğin, döndürmenin 86400 saniyede bir yapılacağı belirtilmişse, strftime(3) biçeminde oluşturulan saat, dakika ve saniye alanları, 24 saatlik sürenin başlangıcını (geceyarısı) göstermek üzere sıfırlarla doldurulur.

strftime(3) dosyaismi biçemlemesi kullanılırken, günlük dosyası biçeminin günlük dosyası döndürülürken her zaman farklı bir dosya ismi üretecek yeterlilikte parçacıklı yapıya sahip olduğundan emin olmalısınız. Aks takdirde döndürme işlemi yeni bir dosya başlatmak yerine hep aynı dosyanın üzerine yazar. Örneğin, logfile için /var/log/errorlog.%Y-%m-%d belirtilmişse 5 mega baytta bir yeni bir günlük dosyasına başlanacaktır. Fakat 5 megabayta gün içinde iki kez ulaşılırsa aynı günlük dosyası üretilir ve günlük hep aynı dosyanın üzerine yazılır.

süre
Günlük dosyasının yenisinin kaç saniyede bir açılacağı belirtilir. Örneğin, bu süre 3600 saniye ise günlük dosyası her saat başında yenilenir; 86400 saniye ise her geceyarısı yenilenir. (Bu süre zarfında günlüğe kaydedilecek bir olay gerçekleşmemişse dosya oluşturulmaz.)
boyut(B|K|M|G)
Boyuta göre döndürme için azami dosya boyutu. Belirtilenin bir süre değil de bir boyut değeri olarak ele alınması için değerin sonuna şu karakterlerden biri eklenmelidir: B (Bayt), K (kilobayt), M (megabayt), G (gigabayt).

Süre ve boyut birlikte belirtilmişse boyut süreden sonra belirtilmelidir. Dosya yenilemesi, bunlardan hangisi daha önce aşılırsa o zaman gerçekleşir.

saat_farkı
Koordinatlı evrensel zamana göre "dakika" farkı. Belirtilmezse, sıfır öntanımlıdır. Örneğin, -5 saatlik bir zaman diliminde bulunuyorsanız bu değer -300 olmalıdır. Çoğu durumda, bunun yerine -l seçeneğini kullanmak gerekir.

Örnekler

CustomLog "|bin/rotatelogs /var/log/logfile 86400" common

nnnn, günlük kaydının başladığı sistem zamanı olmak üzere /var/log/logfile.nnnn dosyası oluşturulur. Bu zaman, daima döngü süresinin katları olacağından bunu cron betiklerinizi eşzamanlamakta kullanabilirsiniz. Her döngü süresinin sonunda (burada 24 saat sonra) yeni bir günlük dosyası açılır.

CustomLog "|bin/rotatelogs -l /var/log/logfile.%Y.%m.%d 86400" common

yyyy, yıl; mm, ay; dd, ayın gününü belirtmek üzere /var/log/logfile.yyyy.mm.dd dosyası oluşturulur. Her gün yerel zamanla geceyarısı yeni bir günlük dosyasına geçilecektir.

CustomLog "|bin/rotatelogs /var/log/logfile 5M" common

Günlük dosyası 5 megabaytlık olunca yenisinin oluşturulmasını sağlar.

ErrorLog "|bin/rotatelogs /var/log/errorlog.%Y-%m-%d-%H_%M_%S 5M"

Hata günlüğünün 5 megabaytta bir errorlog.YYYY-mm-dd-HH_MM_SS biçemli bir isimle oluşturulmasını sağlar.

CustomLog "|bin/rotatelogs -t /var/log/logfile 86400" common

/var/log/logfile dosyasını oluşturur, sunucu başlatılırken ve günde bir kere dosyanın tepesi kırpılır. Bu senaryoda ayrı bir sürecin (tail gibi) dosyayı gerçek zamanlı işleyeceği umulur.

Taşınabilirlik

Aşağıdaki günlük dosyası biçem belirteçlerinin tüm strftime(3) gerçeklenimlerince desteklenmesi gerekir. Kullandığınız kütüphaneye özgü belirteçler için sisteminizdeki strftime(3) kılavuz sayfasına bakınız.

%A | tam gün ismi (yerelleştirilmiş)
%a | 3 harflik gün ismi (yerelleştirilmiş)
%B | tam ay ismi (yerelleştirilmiş)
%b | 3 harflik ay ismi (yerelleştirilmiş)
%c | tarih ve saat (yerelleştirilmiş)
%d | 2 haneli ay günü numarası
%H | 2 haneli saat (24 saatlik)
%I | 2 haneli saat (12 saatlik)
%j | 3 hanelik yıl günü numarası
%M | 2 haneli dakika
%m | 2 haneli ay
%p | 12 saatlik kip için öö/ös (yerelleştirilmiş)
%S | 2 haneli saniye
%U | 2 haneli yılın hafta numarası (Haftanın ilk gününün Pazar olduğu varsayımıyla)
%W | 2 haneli yılın hafta numarası (Haftanın ilk gününün Pazartesi olduğu varsayımıyla)
%w | 1 hanelik haftanın gün numarası (Haftanın ilk gününün Pazar olduğu varsayımıyla)
%X | saat (yerelleştirilmiş)
%x | tarih (yerelleştirilmiş)
%Y | 4 hanelik yıl
%y | 2 hanelik yıl
%Z | zaman dilimi ismi
%% | `%' iminin kendisi

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


split-logfile - Split up multi-vhost logfiles - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Programs

split-logfile - Split up multi-vhost logfiles

This perl script will take a combined Web server access log file and break its contents into separate files. It assumes that the first field of each line is the virtual host identity, put there using the "%v" variable in LogFormat.

Usage

Create a log file with virtual host information in it:

LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined_plus_vhost
CustomLog logs/access_log combined_plus_vhost

Log files will be created, in the directory where you run the script, for each virtual host name that appears in the combined log file. These logfiles will named after the hostname, with a .log file extension.

The combined log file is read from stdin. Records read will be appended to any existing log files.

split-logfile < access_log


suexec - harici programları çalıştırmadan önce kullanıcıyı değiştirir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

suexec - harici programları çalıştırmadan önce kullanıcıyı değiştirir

suexec, CGI programlarını çalıştırmadan önce Apache HTTP Sunucusu tarafından kullanıcı değiştirmek için kullanılır. Bunu yapabilmek için sunucunun root tarafından çalıştırılmış olması gerekir. HTTP artalan süreci normalde root aidiyetinde çalışmadığından suexec'in çalıştırılabilir dosyasının sahibi root olmalı, setuid biti etkin (u+s) olmalı ve dosyaya root dışında hiç kimse yazamamalıdır.

suexec güvenlik modeli ve kavramlar hakkında bilgi edinmek için suexec belgesine (http://httpd.apache.org/docs/2.4/suexec.html) bakınız.

Kullanım

suexec -V

Seçenekler

-V
root iseniz, bu seçenek suexec derleme seçeneklerini gösterir. Güvenlik sebebiyle tüm yapılandırma seçenekleri sadece derleme sırasında değiştirilebilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Diğer Programlar - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Programlar

Diğer Programlar

Bu sayfada daha önce belgelenen programlar şimdi kendi belgelerine sahiptir. Bu sayfaya verilmiş bağlantıları lütfen güncelleyin.

log_server_status

split-logfile

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Çeşitli Belgeler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Çeşitli Belgeler

Aşağıda listelenen belgeler de Apache HTTP sunucusu geliştirme projesi kapsamındadır.

Uyarı

Aşağıdaki belgeler, Apache HTTP Sunucusunun 2.1 sürümünde yapılmış değişikliklere göre tam olarak güncellenmemiştir. Hala güncel kalmış bazı bilgiler olabilir, fakat siz yine de bu belgeleri kullanırken dikkatli olun.

Başarım Arttırma İpuçları - Apache’ye İnce Ayar Çekilmesi

Yüksek başarım elde etmek için Apache yapılandırmasında (çalışma anında ve derleme sırasında) yapılacaklar ile ilgili bazı bilgiler yanında Apache’de bazı şeylerin (bir şeyleri hızlandıran ve yavaşlatan şeylerin) yapılma ve yapılmama sebepleri açıklanmıştır.

Güvenlik İpuçları

Apache HTTP sitenizi güvenli kılmak için yapılacaklar ve yapılmayacaklar.

İlgili Standartlar

Bu belge Apache’nin uyacağı standartların bir çoğuna atıfta bulunmak amacıyla hazırlanmıştır.

Parola Şifreleme Biçimleri

Belgede, kimlik doğrulama amacıyla Apache tarafından desteklenen çeşitli şifreleme tekniklerinden bahsedilmiştir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Apache’de Başarımın Arttırılması - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Çeşitli Belgeler

Apache’de Başarımın Arttırılması

Apache 2.x, esneklik, taşınabilirlik ve başarım arasında bir denge sağlamak üzere tasarlanmış genel amaçlı bir HTTP sunucusudur. Başka sunucularla kıyaslama denemelerinde öne geçmek üzere tasarlanmamış olsa da Apache 2.x gerçek yaşamda karşılaşılan pek çok durumda oldukça yüksek bir başarıma ulaşacak yetenektedir.

Apache 1.3 ile karşılaştırıldığında 2.x sürümleri toplam veri hızını ve ölçeklenebilirliği arttırmak için pek çok en iyileme seçeneği içerir. Bu iyileştirmelerin pek çoğu zaten öntanımlı olarak etkin olmakla birlikte derleme ve kullanım sırasında başarımı önemli ölçüde etkileyebilen yapılandırma seçenekleri de mevcuttur. Bu belgede, bir Apache 2.x kurulumunda sunucu yöneticisinin sunucunun başarımını arttırmak amacıyla yapılandırma sırasında neler yapabileceğinden bahsedilmiştir. Bu yapılandırma seçeneklerinden bazıları, httpd’nin donanımın ve işletim sisteminin olanaklarından daha iyi yararlanabilmesini sağlarken bir kısmı da daha hızlı bir sunum için yöneticinin işlevsellikten ödün verebilmesini olanaklı kılar.

Donanım ve İşletim Sistemi ile İlgili Konular

HTTP sunucusunun başarımını etkileyen en önemli donanım bellektir (RAM). Bir HTTP sunucusu asla takaslama yapmamalıdır. Çünkü takaslama, kullanıcının "yeterince hız" umduğu noktada sunumun gecikmesine sebep olur. Böyle bir durumda kullanıcılar yüklemeyi durdurup tekrar başlatma eğilimindedirler; sonuçta yük daha da artar. MaxRequestWorkers yönergesinin değerini değiştirerek takaslamaya sebep olabilecek kadar çok çocuk süreç oluşturulmasını engelleyebilirsiniz ve böyle bir durumda bunu mutlaka yapmalısınız. Bunun için yapacağınız işlem basittir: top benzeri bir araç üzerinden çalışan süreçlerinizin bir listesini alıp Apache süreçlerinizin ortalama büyüklüğünü saptayıp, mevcut bellekten bir kısmını diğer süreçler için ayırdıktan sonra kalan miktarı bu değere bölerseniz yönergeye atayacağınız değeri bulmuş olursunuz.

Donanımın diğer unsurları için kararı siz verin: Daha hızlı işlemci, daha hızlı ağ kartı, daha hızlı disk; daha hızlının ne kadar hızlı olacağını deneyimlerinize bağlı olarak tamamen sizin ihtiyaçlarınız belirler.

İşletim sistemi seçimi büyük oranda yerel ilgi konusudur. Fakat yine de, genelde yararlılığı kanıtlanmış bazı kurallar bu seçimde size yardımcı olabilir:

  • Seçtiğiniz işletim sisteminin (çekirdeğin) en son kararlı sürümünü çalıştırın. Bir çok işletim sistemi, son yıllarda TCP yığıtları ve evre kütüphaneleri ile ilgili belirgin iyileştirmeler yapmışlar ve yapmaktadırlar.

  • İşletim sisteminiz sendfile(2) sistem çağrısını destekliyorsa bunun etkinleştirilebildiği sürümün kurulu olması önemlidir. (Örneğin, Linux için bu, Linux 2.4 ve sonraki sürümler anlamına gelirken, Solaris için Solaris 8’den önceki sürümlerin yamanması gerektirdiği anlamına gelmektedir.) sendfile işlevinin desteklendiği sistemlerde Apache 2 duruk içeriği daha hızlı teslim etmek ve işlemci kullanımını düşürmek amacıyla bu işlevselliği kullanacaktır.

Çalışma Anı Yapılandırması ile İlgili Konular

İlgili Modüller İlgili Yönergeler
  • mod_dir
  • mpm_common
  • mod_status
  • AllowOverride
  • DirectoryIndex
  • HostnameLookups
  • EnableMMAP
  • EnableSendfile
  • KeepAliveTimeout
  • MaxSpareServers
  • MinSpareServers
  • Options
  • StartServers

HostnameLookups ve DNS ile ilgili diğer konular

Apache 1.3 öncesinde, HostnameLookups yönergesinin öntanımlı değeri On idi. İstek yerine getirilmeden önce bir DNS sorgusu yapılmasını gerektirmesi sebebiyle bu ayarlama her istekte bir miktar gecikmeye sebep olurdu. Apache 1.3’ten itibaren yönergenin öntanımlı değeri Off yapılmıştır. Eğer günlük dosyalarınızda konak isimlerinin bulunmasını isterseniz, Apache ile birlikte gelen logresolve programını kullanabileceğiniz gibi günlük raporlarını çözümleyen Apache ile gelmeyen programlardan herhangi birini de kullanabilirsiniz.

Günlük dosyaları üzerindeki bu işlemi sunucu makinesi dışında günlük dosyasının bir kopyası üzerinde yapmanızı öneririz. Aksi takdirde sunucunuzun başarımı önemli ölçüde etkilenebilir.

Allow veya Deny yönergelerinde IP adresi yerine bir konak veya alan ismi belirtirseniz, iki DNS sorguluk bir bedel ödersiniz (biri normal, diğeri IP taklidine karşı ters DNS sorgusu). Başarımı en iyilemek için bu yönergelerde mümkün olduğunca isim yerine IP adreslerini kullanınız.

HostnameLookups yönergelerinin <Location "/server-status"> gibi bölüm yönergelerinin içinde de yer alabileceğini unutmayın. Bu gibi durumlarda DNS sorguları sadece istek kuralla eşleştiği takdirde yapılacaktır. Aşağıdaki örnekte .html ve .cgi dosyalarına yapılan istekler hariç DNS sorguları iptal edilmektedir:

HostnameLookups off
<Files ~ "\.(html|cgi)$">
  HostnameLookups on
</Files>

Yine de bazı CGI’lerin DNS isimlerine ihtiyacı olursa bu CGI’lerin bu ihtiyaçlarına yönelik olarak gethostbyname çağrıları yapabileceğini gözardı etmeyiniz.

FollowSymLinks ve SymLinksIfOwnerMatch

URL uzayınızda geçerli olmak üzere bir Options FollowSymLinks yoksa veya Options SymLinksIfOwnerMatch yönergeleri varsa, Apache her sembolik bağın üzerinde bazı sınamalar yapmak için ek bir sistem çağrısından başka istenen her dosya için de ayrı bir çağrı yapacaktır.

DocumentRoot "/siteler/htdocs"
<Directory />
  Options SymLinksIfOwnerMatch
</Directory>

Bu durumda /index.html için bir istek yapıldığında Apache, /siteler, /siteler/htdocs ve
/siteler/htdocs/index.html üzerinde lstat(2) çağrıları yapacaktır. lstat sonuçları önbelleğe kaydedilmediğinden bu işlem her istekte yinelenecektir. Amacınız gerçekten sembolik bağları güvenlik açısından sınamaksa bunu şöyle yapabilirsiniz:

DocumentRoot "/siteler/htdocs"
<Directory "/">
  Options FollowSymLinks
</Directory>

<Directory "/siteler/htdocs">
  Options -FollowSymLinks +SymLinksIfOwnerMatch
</Directory>

Böylece DocumentRoot altındaki dosyalar için fazladan bir çağrı yapılmasını engellemiş olursunuz. Eğer bazı bölümlerde Alias, RewriteRule gibi yönergeler üzerinden belge kök dizininizin dışında kalan dosya yollarına sahipseniz benzer işlemleri onlar için de yapmalısınız. Sembolik bağ koruması yapmamak suretiyle başarımı arttırmak isterseniz, FollowSymLinks seçeneğini her yerde etkin kılın ve SymLinksIfOwnerMatch seçeneğini asla etkinleştirmeyin.

AllowOverride

Genellikle .htaccess dosyaları üzerinden yapıldığı gibi URL uzayınızda geçersizleştirmelere izin veriyorsanız, Apache her dosya bileşeni için bu .htaccess dosyalarını açmaya çalışacaktır.

DocumentRoot "/siteler/htdocs"
<Directory "/">
  AllowOverride all
</Directory>

Bu durumda /index.html sayfasına yapılan bir istek için Apache, /.htaccess, /siteler/.htaccess ve /siteler/htdocs/.htaccess dosyalarını açmaya çalışacaktır. Çözüm Options FollowSymLinks durumunun benzeridir; başarımı arttırmak için dosya sisteminizin her yerinde AllowOverride None olsun.

Dil Uzlaşımı

Başarımı son kırıntısına kadar arttırmak istiyorsanız, mümkünse içerik dili uzlaşımı da yapmayın. Dil uzlaşımından yararlanmak isterken büyük başarım kayıplarına uğrayabilirsiniz. Böyle bir durumda sunucunun başarımını arttırmanın tek bir yolu vardır.

DirectoryIndex index

Yukarıdaki gibi bir dosya ismi kalıbı kullanmak yerine, aşağıdaki gibi seçenekleri tam bir liste halinde belirtin:

DirectoryIndex index.cgi index.pl index.shtml index.html

Buradaki sıralama öncelik sırasını belirler; yani, öncelikli olmasını istediğiniz seçeneği listenin başına yazmalısınız.

İstenen dosya için MultiViews kullanarak dizini taratmak yerine, gerekli bilgiyi tek bir dosyadan okutmak suretiyle başarımı arttırabilirsiniz. Bu amaçla türeşlem (type-map) dosyaları kullanmanız yeterli olacaktır.

Sitenizde içerik dili uzlaşımına gerek varsa, bunu Options MultiViews yönergesi üzerinden değil, türeşlem dosyaları kullanarak yapmayı deneyin. İçerik dili uzlaşımı ve türeşlem dosyalarının oluşturulması hakkında daha ayrıntılı bilgi edinmek için İçerik Uzlaşımı belgesine bakınız.

Bellek Eşlemleri

Apache’nin SSI sayfalarında olduğu gibi teslim edilecek dosyanın içeriğine bakma gereği duyduğu durumlarda, eğer işletim sistemi mmap(2) ve benzerlerini destekliyorsa çekirdek normal olarak dosyayı belleğe kopyalayacaktır.

Bazı platformlarda bu belleğe eşleme işlemi başarımı arttırsa da başarımın veya httpd kararlılığının zora girdiği durumlar olabilmektedir:

  • Bazı işletim sistemlerinde işlemci sayısı artışına bağlı olarak, mmap işlevi read(2) kadar iyi ölçeklenmemiştir. Örneğin, çok işlemcili Solaris sunucularda mmap iptal edildiği takdirde içeriği sunucu tarafından işlenen dosyalar üzerinde bazen daha hızlı işlem yapılabilmektedir.

  • Belleğe kopyalanacak dosya NFS üzerinden bağlanan bir dosya sistemindeyse ve dosya başka bir NFS istemcisi makine tarafından silinmiş veya dosyanın boyutu değiştirilmişse sunucunuz dosyaya tekrar erişmeye çalıştığında bir hata alabilecektir.

Böyle durumların olasılık dahilinde olduğu kurulumlarda içeriği sunucu tarafından işlenecek dosyaların belleğe kopyalanmaması için yapılandırmanıza EnableMMAP off satırını ekleyiniz. (Dikkat: Bu yönerge dizin seviyesinde geçersizleştirilebilen yönergelerdendir.)

sendfile

Apache’nin duruk dosyalarda olduğu gibi teslim edilecek dosyanın içeriğine bakmadığı durumlarda, eğer işletim sistemi sendfile(2) desteğine sahipse çekirdek normal olarak bu desteği kullanacaktır.

Bazı platformlarda sendfile kullanımı, okuma ve yazma işlemlerinin ayrı ayrı yapılmamasını sağlasa da sendfile kullanımının httpd kararlılığını bozduğu bazı durumlar sözkonusudur:

  • Bazı platformlar derleme sisteminin saptayamadığı bozuk bir sendfile desteğine sahip olabilir. Özellikle derleme işleminin başka bir platformda yapılıp sendfile desteği bozuk bir makineye kurulum yapıldığı durumlarda bu desteğin bozuk olduğu saptanamayacaktır.

  • Çekirdek, NFS üzerinden erişilen ağ dosyalarını kendi önbelleği üzerinden gerektiği gibi sunamayabilir.

Böyle durumların olasılık dahilinde olduğu kurulumlarda içeriğin sendfile desteğiyle teslim edilmemesi için yapılandırmanıza EnableSendfile off satırını ekleyiniz. (Dikkat: Bu yönerge dizin seviyesinde geçersizleştirilebilen yönergelerdendir.)

Süreç Oluşturma

Apache 1.3 öncesinde MinSpareServers, MaxSpareServers ve StartServers ayarları, başka sunucularla kıyaslama denemelerinde olağanüstü kötü sonuçlar alınmasına sebep olmaktaydı. Özellikle uygulanan yükü karşılamaya yetecek sayıda çocuk süreç oluşturulması aşamasında Apache’nin elde ettiği ivme bunlardan biriydi. Başlangıçta StartServers yönergesiyle belli sayıda süreç oluşturulduktan sonra her saniyede bir tane olmak üzere MinSpareServers sayıda çocuk süreç oluşturulmaktaydı. Örneğin, aynı anda 100 isteğe yanıt vermek için StartServers yönergesinin öntanımlı değeri olarak başta 5 süreç oluşturulduğundan kalan süreçler için 95 saniye geçmesi gerekirdi. Sık sık yeniden başlatılmadıklarından dolayı gerçek hayatta sunucuların başına gelen de buydu. Başka sunucularla kıyaslama denemelerinde ise işlem sadece on dakika sürmekte ve içler acısı sonuçlar alınmaktaydı.

Saniyede bir kuralı, sunucunun yeni çocukları oluşturması sırasında sistemin aşırı meşgul duruma düşmemesi için alınmış bir önlemdi. Makine çocuk süreç oluşturmakla meşgul edildiği sürece isteklere yanıt veremeyecektir. Böylesi bir durum Apache’nin başarımını kötüleştirmekten başka işe yaramayacaktır. Apache 1.3’te saniyede bir kuralı biraz esnetildi. Yeni gerçeklenimde artık bir süreç oluşturduktan bir saniye sonra iki süreç, bir saniye sonra dört süreç oluşturulmakta ve işlem, saniyede 32 çocuk süreç oluşturulur duruma gelene kadar böyle ivmelenmektedir. Çocuk süreç oluşturma işlemi MinSpareServers değerine ulaşılınca durmaktadır.

Bu, MinSpareServers, MaxSpareServers ve StartServers ayarlarıyla oynamayı neredeyse gereksiz kılacak kadar iyi sonuçlar verecek gibi görünmektedir. Saniyede 4 çocuktan fazlası oluşturulmaya başlandığında hata günlüğüne bazı iletiler düşmeye başlar. Bu iletilerin sayısı çok artarsa bu ayarlarla oynama vakti gelmiş demektir. Bunun için mod_status çıktısını bir kılavuz olarak kullanabilirsiniz.

Süreç oluşturmayla ilgili olarak süreç ölümü MaxConnectionsPerChild değeri ile sağlanır. Bu değer öntanımlı olarak 0 olup, çocuk süreç başına istek sayısının sınırsız olduğu anlamına gelir. Eğer yapılandırmanızda bu değeri 30 gibi çok düşük bir değere ayarlarsanız bunu hemen kaldırmak zorunda kalabilirsiniz. Sunucunuzu SunOS veya Solaris’in eski bir sürümü üzerinde çalıştırıyorsanız bellek kaçaklarına sebep olmamak için bu değeri 10000 ile sınırlayınız.

Kalıcı bağlantı özelliğini kullanıyorsanız, çocuk süreçler zaten açık bağlantılardan istek beklemekte olacaklardır. KeepAliveTimeout yönergesinin öntanımlı değeri 5 saniye olup bu etkiyi en aza indirmeye yönelik süredir. Burada ağ band genişliği ile sunucu kaynaklarının kullanımı arasında bir seçim yapmak söz konusudur. Hiçbir şey umurunuzda değilse çoğu ayrıcalığın yitirilmesi pahasına bu değeri rahatça 60 saniyenin üzerine çıkarabilirsiniz.

Derleme Sırasında Yapılandırma ile İlgili Konular

MPM Seçimi

Apache 2.x, Çok Süreçlilik Modülleri (MPM) adı verilen eklemlenebilir çok görevlilik modellerini destekler. Apache’yi derlerken bu MPM’lerden birini seçmeniz gerekir. MPM’lerden bazıları platformlara özeldir: mpm_netware, mpmt_os2 ve mpm_winnt. Unix benzeri sistemler için ise seçebileceğiniz modül sayısı birden fazladır. MPM seçiminin httpd’nin hızında ve ölçeklenebilirliğinde bazı etkileri olabilir:

  • worker modülü her biri çok evreli çok sayıda çocuk süreç kullanımını destekler. Her evre aynı anda tek bir bağlantıya hizmet sunar. Aynı hizmeti daha az bellek harcayarak vermesi nedeniyle yüksek trafiğe sahip sunucularda prefork modülüne göre daha iyi bir seçimdir.
  • event modülü worker modülü gibi çok evreli bir modüldür, fakat aunı anda dahafazla isteğe yanıt verecek şekilde tasarlanmıştır. Bunu, evreleri destekleyen bazı işlemleri yapmamak suretiyle yeni isteklerle çalışacak ana evreleri serbestleştirerek sağlar.
  • prefork modülü her biri tek bir evreye sahip çok sayıda çocuk süreç kullanımını destekler. Her süreç aynı anda tek bir bağlantıya hizmet sunar. Çoğu sistemde daha hızlı olması nedeniyle worker modülüne göre daha iyi bir seçim olarak görünürse de bunu daha fazla bellek kullanarak sağlar. prefork modülünün evresiz tasarımının worker modülüne göre bazı yararlı tarafları vardır: Çok evreli sistemlerde güvenilir olmayan üçüncü parti modülleri kullanabilir ve evrelerde hata ayıklamanın yetersiz kaldığı platformlarda hatalarını ayıklamak daha kolaydır.

Bu modüller ve diğerleri hakkında daha ayrıntılı bilgi edinmek için Çok Süreçlilik Modülleri belgesine bakınız.

Modüller

Bellek kullanımı başarım konusunda önemli olduğundan gerçekte kullanmadığınız modülleri elemeye çalışmalısınız. Modülleri birer DSO olarak derlediyseniz LoadModule yönergesinin bulunduğu satırı açıklama haline getirmeniz modülden kurtulmanız için yeterli olacaktır. Modülleri bu şekilde kaldırarak onların yokluğunda sitenizin hala işlevlerini yerine getirdiğini görme şansına da kavuşmuş olursunuz.

Ancak, eğer modülleri Apache çalıştırılabilirinin içine gömmüşseniz istenmeyen modülleri kaldırmak için Apache'yi yeniden derlemeniz gerekir.

Bu noktada bir soru akla gelebilir: Hangi modüller gerekli, hangileri değil? Bu sorunun yanıtı şüphesiz siteden siteye değişir. Ancak, olmazsa olmaz moüller olarak mod_mime, mod_dir ve mod_log_config modüllerini sayabiliriz. Bunlardan mod_log_config olmadan da bir sitenin çalışabileceğinden hareketle bu modülün varlığı isteğe bağlı olsa da bu modülü kaldırmanızı önermiyoruz.

Atomik İşlemler

Worker MPM'nin en son geliştirme sürümleri ve mod_cache gibi bazı modüller APR'nin atomik API'sini kullanırlar. Bu API, düşük ayarlı evre eşzamanlamasında atomik işlemler yapar.

Öntanımlı olarak, APR bu işlemleri hedef işletim sistemi/işlemci platformunda kullanılabilecek en verimli mekanizmayı kullanarak gerçekleştirir. Günümüz işlemcilerinin çoğu, örneğin, bir atomik karşılaştırma ve takas (CAS) işlemini donanımda gerçekleştirmektedir. Bazı platformlarda APR'nin atomik işlemler için öntanımlı olarak daha yavaş olan mutekslere dayalı gerçeklenimi kullanmasının sebebi eski işlemcilerde bu tür makine kodlarının yokluğudur. Apache'yi bu tür platformalarda günümüz işlemcileriyde çalıştırmayı düşünüyorsanız Apache'yi derlemek için yapılandırırken en hızlı atomik işlemin seçilebilmesi için --enable-nonportable-atomics seçeneğini kullanın:

./buildconf
./configure --with-mpm=worker --enable-nonportable-atomics=yes

--enable-nonportable-atomics seçeneği şu platformlar için uygundur:

  • SPARC üzerinde Solaris
    APR öntanımlı olarak, SPARC/Solaris üzerinde mutekslere dayalı atomik işlemleri kullanır. Ancak, --enable-nonportable-atomics yapılandırmasını kullanırsanız, donanım üzerinde hızlı karşılaştırma ve takas için uygun SPARC v8plus kodunu kullanacak şekilde kod üretilir. Apache'yi bu seçenekle yapılandırırsanız atomik işlemler daha verimli olacak fakat derlenen Apache çalıştırılabiliri sadece UltraSPARC kırmığı üzerinde çalışacaktır.
  • x86 üzerinde Linux
    APR öntanımlı olarak, Linux üzerinde mutekslere dayalı atomik işlemleri kullanır. Ancak, --enable-nonportable-atomics yapılandırmasını kullanırsanız, donanım üzerinde hızlı karşılaştırma ve takas için uygun 486 kodunu kullanacak şekilde kod üretilir. Apache'yi bu seçenekle yapılandırırsanız atomik işlemler daha verimli olacak fakat derlenen Apache çalıştırılabiliri (386 üzerinde değil) sadece 486 ve sonrası kırmıklarda çalışacaktır.

mod_status ve ExtendedStatus On

mod_status modülünü derlemiş ve Apache'yi yapılandırır ve çalıştırırken ExtendedStatus On satırını da kullanmışsanız Apache her istek üzerinde gettimeofday(2) (veya işletim sistemine bağlı olarak time(2)) çağrısından başka (1.3 öncesinde) fazladan defalarca time(2) çağrıları yapacaktır. Bu çağrılarla durum raporununun zamanlama bilgilerini içermesi sağlanır. Başarımı arttırmak için ExtendedStatus off yapın (zaten öntanımlı böyledir).

accept dizgilemesi ve çok soketli işlem

Uyarı:

Bu bölüm, Apache HTTP sunucusunun 2.x sürümlerinde yapılan değişikliklere göre tamamen güncellenmemiştir. Bazı bilgiler hala geçerliyse de lütfen dikkatli kullanınız.

Burada Unix soket arayüzü gerçeklenirken ihmal edilen bir durumdan bahsedeceğiz. HTTP sunucunuzun çok sayıda adresten çok sayıda portu dinlemek için çok sayıda Listen yönergesi kullanmakta olduğunu varsayalım. Her soketi çalıştığını görmek için denerken Apache bağlantı için select(2) kullanacaktır. select(2) çağrısı bu soketin üzerinde sıfır veya en azından bir bağlantının beklemekte olduğu anlamına gelir. Apache'nin modeli çok sayıda çocuk süreç içerir ve boşta olanların tümünde aynı anda yeni bağlantılar denenebilir. Gerçekte çalışan kod bu olmasa da meramımızı anlatmak için kodun şöyle bir şey olduğunu varsayabiliriz:

        for (;;) {
          for (;;) {
            fd_set accept_fds;

            FD_ZERO (&accept_fds);
            for (i = first_socket; i <= last_socket; ++i) {
              FD_SET (i, &accept_fds);
            }
            rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
            if (rc < 1) continue;
            new_connection = -1;
            for (i = first_socket; i <= last_socket; ++i) {
              if (FD_ISSET (i, &accept_fds)) {
                new_connection = accept (i, NULL, NULL);
                if (new_connection != -1) break;
              }
            }
            if (new_connection != -1) break;
          }
          process_the(new_connection);
        }

Bu özet gerçeklenim bir takım açlık sorunlarına sebep olur. Bu döngünün çalışması sırasında aynı anda çok sayıda çocuk süreç yeniden çağrılır ve istekler arasında kalan çoğu çocuk da select ile engellenir. Engellenen tüm bu çocuklar soketlerden herhangi biri üzerinde tek bir istek göründüğünde select tarafından uyandırılıp işleme sokulmak üzere döndürülürler. (Uyandırılan çocuk sayısı işletim sistemine ve zamanlama ayarlarına göre değişiklik gösterir,) Bunların hepsi döngüye katılıp bağlantı kabul etmeye (accept) çalışırlar. Fakat içlerinden yalnız biri (sadece bir bağlantı isteğinin mevcut olduğu varsayımıyla) bunu başarabilir. Kalanının bağlantı kabul etmesi (accept) engellenir. Bu durum, bu çocukları istekleri başka başka soketlerden değil mecburen tek bir soketten kabul etmeye kilitler ve bu soket üzerinde yeni bir istek belirip uyandırılana kadar bu durumda kalırlar. Bu açlık sorunu ilk olarak PR#467 sayılı raporla belgelenmiştir. Bu sorunun en az iki çözümü vardır.

Çözümün biri engellenmeyen soket kullanımıdır. Bu durumda accept çocukları engellemeyecek ve yapılan bir bağlantının ardından diğer çocuklar durumları değişmeksizin bağlantı beklemeye devam edeceklerdir. Fakat bu durum işlemci zamanının boşa harcanmasına sebep olur. Seçilmiş (select) boşta on çocuğun olduğunu ve bir bağlantı geldiğini varsayalım. Kalan dokuz çocuk işine devam edip bağlantı kabul etmeyi (accept) deneyecek, başarızsız olacak, dönecek başa, tekrar seçilecek (select) ve böyle hiçbir iş yapmadan dönüp duracaktır. Bu arada hizmet sunmakta olanlar da işlerini bitirdikten sonra bu döngüdeki yerlerini alacaklardır. Aynı kutunun içinde boşta bir sürü işlemciniz (çok işlemcili sistemler) yoksa bu çözüm pek verimli olmayacaktır.

Diğer çözüm ise Apache tarafından kullanılan çözüm olup, girdiyi bir iç döngüde sıraya sokmaktır. Döngü aşağıda örneklenmiştir (farklar vurgulanmıştır):

        for (;;) {
          accept_mutex_on ();
          for (;;) {
            fd_set accept_fds;

            FD_ZERO (&accept_fds);
            for (i = first_socket; i <= last_socket; ++i) {
              FD_SET (i, &accept_fds);
            }
            rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
            if (rc < 1) continue;
            new_connection = -1;
            for (i = first_socket; i <= last_socket; ++i) {
              if (FD_ISSET (i, &accept_fds)) {
                new_connection = accept (i, NULL, NULL);
                if (new_connection != -1) break;
              }
            }
            if (new_connection != -1) break;
          }
          accept_mutex_off ();
          process the new_connection;
        }

accept_mutex_on ve accept_mutex_off işlevleri bir karşılıklı red semoforu oluştururlar. Mutekse aynı anda sadece bir çocuk sahip olabilir. Bu muteksleri gerçeklemek için çeşitli seçenekler vardır. Seçim, src/conf.h (1.3 öncesi) veya src/include/ap_config.h (1.3 ve sonrası) dosyasında tanımlanmıştır. Bazı mimariler bir kilitleme seçeneğine sahip değildir. Böyle mimarilerde çok sayıda Listen yönergesi kullanmak güvenilir olmayacaktır.

Mutex yönergesi, mpm-accept muteks gerçeklenimini çalışma anında değiştirmek için kullanılabilir. Farklı muteks gerçeklenimleri ile ilgili hususlar bu yönergede belgelenmiştir.

Başka bir çözüm daha vardır ancak döngü kısmen dizgilenmeyeceğinden (yani belli sayıda sürece izin verilemeyeceğinden) asla gerçeklenmemiştir. Bu sadece, aynı anda çok sayıda çocuk sürecin çalışabileceği ve dolayısıyla band genişliğinin tüm yönleriyle kullanılabileceği çok işlemcili sistemlerde ilginç olabilirdi. Bu gelecekte incelenmeye değer bir konu olmakla beraber çok sayıda HTTP sunucusunun aynı anda aynı amaca hizmet edecek şekilde çalışması standart olarak pek mümkün görülmediğinden bu olasılık çok düşüktür.

En yüksek başarımı elde etmek için ideal olanı sunucuları çalıştırırken çok sayıda Listen yönergesi kullanmamaktır. Fakat siz yine de okumaya devam edin.

accept dizgilemesi - tek soket

Çok soketli sunucular için yukarıda açıklananlar iyi güzel de tek soketli sunucularda durum ne? Kuramsal olarak, bunların hiçbiriyle bir sorunları olmaması gerekir. Çünkü yeni bir bağlantı gelene kadar tüm çocuklar accept(2) ile engellenirler dolayısıyla hiçbir açlık sorununun ortaya çıkmaması gerekir. Uygulamada ise son kullanıcıdan gizli olarak, yukarıda engellenmeyen çocuklar çözümünde bahsedilenle hemen hemen aynı "boşa dönüp durma" davranışı mevcuttur. Çoğu TCP yığıtı bu yolu gerçeklemiştir. Çekirdek, yeni bir bağlantı ortaya çıktığında accept ile engellenen tüm süreçleri uyandırır. Bu süreçlerden bağlantıyı alan kullanıcı bölgesine geçerken çekirdek içinde döngüde olan diğerleri de yeni bağlantı keşfedilene kadar uykularına geri dönerler. Bu çekirdek içi döngü, kullanıcı bölgesindeki kodlara görünür değildir ama bu olmadıkları anlamına gelmez. Bu durum, çok soketli engellenmeyen çocuklar çözümündeki boşa döngünün sebep olduğu gereksiz işlemci yükü sorununu içinde barındırır.

Bununla birlikte, tek soketli durumda bile bundan daha verimli bir davranış sergileyen bir çok mimari bulduk. Bu aslında hemen hemen her durumda öntanımlı olarak böyledir. Linux altında yapılan üstünkörü denemelerde (128MB bellekli çift Pentium pro 166 işlemcili makinede Linux 2.0.30) tek sokette dizgilemenin dizgilenmemiş duruma göre saniyede %3 daha az istekle sonuçlandığı gösterilmiştir. Fakat dizgilenmemiş tek soket durumunda her istekte 100ms'lik ek bir gecikme olduğu görülmüştür. Bu gecikmenin sebebi muhtemelen uzun mesafeli hatlar olup sadece yerel ağlarda söz konusudur. Tek soketli dizgilemeyi geçersiz kılmak için SINGLE_LISTEN_UNSERIALIZED_ACCEPT tanımlarsanız tek soketli sunucularda artık dizgileme yapılmayacaktır.

Kapatmayı zamana yaymak

draft-ietf-http-connection-00.txt taslağının 8. bölümünde bahsedildiği gibi, bir HTTP sunucusunun protokolü güvenilir şekilde gerçeklemesi için her iki yöndeki iletişimi birbirinden bağımsız olarak (iki yönlü bir TCP bağlantısının her yarısını diğerinden bağımsız olarak) kapatması gerekir.

Bu özellik Apache'ye eklendiğinde Unix'in çeşitli sürümlerinde uzgörüsüzlükten dolayı bir takım geçici telaş sorunlarına sebep oldu. TCP belirtimi FIN_WAIT_2 durumunda bir zaman aşımından bahsetmez ama yasaklamaz da. Zaman aşımı olmayan sistemlerde, Apache 1.2 çoğu soketin sonsuza kadar FIN_WAIT_2 durumunda takılıp kalmasına sebep olur. Çoğu durumda, satıcıdan sağlanan en son TCP/IP yamalarını uygulanarak bu önlenebilir. Satıcının hiçbir yeni yama dağıtmadığı durumlarda (örneğin, SunOS4 -- bir kaynak lisansı ile insanlar bunu kendileri yamayabilirse de) bu özelliği devre dışı bırakmaya karar verdik.

Bunun üstesinden gelmenin iki yolu vardır. Bunlardan biri SO_LINGER soket seçeneğidir. Bu işin kaderi buymuş gibi görünürse de çoğu TCP/IP yığıtında bu gerektiği gibi gerçeklenmemiştir. Bu yığıtlar üzerinde, bu yöntemin, doğru bir gerçeklenimle bile (örneğin, Linux 2.0.31) sonraki çözümden daha pahalı olduğu ortaya çıkmıştır.

Çoğunlukla, Apache bunu (http_main.c içindeki) lingering_close adında bir işlevle gerçekler. Bu işlev kabaca şöyle görünür:

        void lingering_close (int s)
        {
          char junk_buffer[2048];

          /* shutdown the sending side */
          shutdown (s, 1);

          signal (SIGALRM, lingering_death);
          alarm (30);

          for (;;) {
            select (s for reading, 2 second timeout);
            if (error) break;
            if (s is ready for reading) {
              if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
                break;
              }
              /* just toss away whatever is here */
            }
          }

          close (s);
        }

Bağlantı sonunda bu doğal olarak biraz daha masrafa yol açar, fakat güvenilir bir gerçeklenim için bu gereklidir. HTTP/1.1'in daha yaygın kullanılmaya başlanması ve tüm bağlantıların kalıcı hale gelmesiyle bu gerçeklenim daha fazla istek üzerinden kendi masrafını karşılayacaktır. Ateşle oynamak ve bu özelliği devre dışı bırakmak isterseniz NO_LINGCLOSE'u tanımlayabilirsiniz, fakat bu asla önerilmez. Özellikle, HTTP/1.1'den itibaren boruhatlı kalıcı bağlantıların lingering_close kullanmaya başlaması mutlak bir gerekliliktir (ve boruhatlı bağlantıların daha hızlı olması nedeniyle bu bağlantıları desteklemek isteyebilirsiniz).

Çetele Dosyası

Apache'nin ana ve alt süreçleri birbirleriyle çetele denen birşey üzerinden haberleşirler. Bunun en mükemmel şekilde paylaşımlı bellekte gerçeklenmesi gerekir. Eriştiğimiz veya portlarını ayrıntılı olarak belirttiğimiz işletim sistemleri için bu, genellikle paylaşımlı bellek kullanılarak gerçeklenir. Geri kalanlar, öntanımlı olarak bunu bir disk dosyası kullanarak gerçekler. Bir disk dosyaı yavaş olmanın yanı sıra güvenilir de değildir (ve daha az özelliğe sahiptir). Mimarinizin src/main/conf.h dosyasını inceleyin ve USE_MMAP_SCOREBOARD veya USE_SHMGET_SCOREBOARD'a bakın. Bu ikisinden birinin (ve yanı sıra sırasıyla HAVE_MMAP veya HAVE_SHMGET'in) tanımlanmış olması, sağlanan paylaşımlı bellek kodunu etkinleştirir. Eğer sisteminiz diğer türdeki paylaşımlı belleğe sahipse, src/main/http_main.c dosyasını açıp, Apache'de bu belleği kullanması gereken kanca işlevleri ekleyin (Bize de bir yama yollayın, lütfen).

Tarihsel bilgi: Apache'nin Linux uyarlaması, Apache'nin 1.2 sürümüne kadar paylaşımlı belleği kullanmaya başlamamıştı. Bu kusur, Apache'nin Linux üzerindeki erken dönem sürümlerinin davranışlarının zayıf ve güvenilmez olmasına yol açmıştı.

DYNAMIC_MODULE_LIMIT

Devingen olarak yüklenen modülleri kullanmamak niyetindeyseniz (burayı okuyan ve sunucunuzun başarımını son kırıntısına kadar arttırmakla ilgilenen biriyseniz bunu düşünmezsiniz), sunucunuzu derlerken seçenekler arasına -DDYNAMIC_MODULE_LIMIT=0 seçeneğini de ekleyin. Bu suretle, sadece, devingen olarak yüklenen modüller için ayrılacak belleği kazanmış olacaksınız.

Ek: Bir çağrı izlemesinin ayrıntılı çözümlemesi

Burada, Solaris 8 üzerinde worker MPM'li Apache 2.0.38'in bir sistem çağrısı izlenmektedir. Bu izleme şu komutla elde edilmiştir:

truss -l -p httpd_çocuk_pidi.

-l seçeneği, truss'a hafif bir sürecin yaptığı her sistem çağrısını (hafif süreç -- HS -- Solaris'in bir çekirdek seviyesi evreleme biçimi) günlüğe yazmasını söyler.

Diğer sistemlerin sistem çağrılarını izleyen farklı araçları vardır (strace, ktrace, par gibi). Bunlar da benzer çıktılar üretirler.

Bu izleme sırasında, bir istemci httpd'den 10 KB'lık duruk bir dosya talebinde bulunmuştur. Duruk olmayan veya içerik uzlaşımlı isteklerin izleme kayıtları vahşice (bazı durumlarda epey çirkince) farklı görünür.

/67: accept(3, 0x00200BEC, 0x00200C0C, 1) (uykuda...)
/67: accept(3, 0x00200BEC, 0x00200C0C, 1) = 9

Bu izlemede, dinleyen evre HS #67 içinde çalışmaktadır.

accept(2) dizgelemesinin olmayışına dikkat edin. Özellikle bu platformda worker MPM, çok sayıda portu dinlemedikçe, öntanımlı olarak dizgeleştirilmemiş bir accept çağrısı kullanır.

/65: lwp_park(0x00000000, 0) = 0
/67: lwp_unpark(65, 1) = 0

Bağlantının kabul edilmesiyle, dinleyici evre isteği yerine getirmek üzere bir worker evresini uyandırır. Bu izlemede, isteği yerine getiren worker evresi HS #65'e aittir.

/65: getsockname(9, 0x00200BA4, 0x00200BC4, 1) = 0

Sanal konakların gerçeklenimi sırasında, Apache'nin, bağlantıları kabul etmek için kullanılan yerel soket adreslerini bilmesi gerekir. Çoğu durumda bu çağrıyı bertaraf etmek mümkündür (hiç sanal konağın olmadığı veya Listen yönergelerinin mutlak adreslerle kullanıldığı durumlarda). Fakat bu en iyilemeleri yapmak için henüz bir çaba harcanmamıştır.

/65: brk(0x002170E8) = 0
/65: brk(0x002190E8) = 0

brk(2) çağrıları devingen bellekten bellek ayırır. httpd çoğu isteği yerine getirirken özel bellek ayırıcılar (apr_pool ve apr_bucket_alloc) kullandığından bunlar bir sistem çağrısı izlemesinde nadiren görünür. Bu izlemede, httpd henüz yeni başlatıldığından, özel bellek ayırıcıları oluşturmak için ham bellek bloklarını ayırmak amacıyla malloc(3) çağrıları yapması gerekir.

/65: fcntl(9, F_GETFL, 0x00000000) = 2
/65: fstat64(9, 0xFAF7B818) = 0
/65: getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B910, 2190656) = 0
/65: fstat64(9, 0xFAF7B818) = 0
/65: getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B914, 2190656) = 0
/65: setsockopt(9, 65535, 8192, 0xFAF7B918, 4, 2190656) = 0
/65: fcntl(9, F_SETFL, 0x00000082) = 0

Ardından, worker evresi istemciye (dosya tanıtıcısı 9) engellenmeyen kipte bir bağlantı açar. setsockopt(2) ve getsockopt(2) çağrıları, Solaris libc'sinin soketler üzerindeki fcntl(2) çağrısı yanında birer yan etkiden ibarettirler.

/65: read(9, " G E T / 1 0 k . h t m".., 8000) = 97

Worker evresi istemciden isteği okur.

/65: stat("/var/httpd/apache/httpd-8999/htdocs/10k.html", 0xFAF7B978) = 0
/65: open("/var/httpd/apache/httpd-8999/htdocs/10k.html", O_RDONLY) = 10

Bu httpd Options FollowSymLinks ve AllowOverride None ile yapılandırılmıştır. Bu bakımdan, ne istenen dosya ile sonuçlanan yol üzerindeki her dizinde lstat(2) çağrısına ne de .htaccess dosyalarına bakılmasına gerek vardır. stat(2) çağrısı basitçe dosya için şunları doğrulamak amacıyla yapılır: 1) dosya mevcuttur ve 2) bir dizin değil normal bir dosyadır.

/65: sendfilev(0, 9, 0x00200F90, 2, 0xFAF7B53C) = 10269

Bu örnekte, httpd, istenen dosyayı ve HTTP yanıt başlığını tek bir sendfilev(2) sistem çağrısı ile göndermektedir. Dosya gönderim işleminin anlamı sistemden sisteme değişiklik gösterir. Bazı sistemlerde, sendfile(2) çağrısından önce başlıkları göndermek için write(2) veya writev(2) çağrısı yapmak gerekir.

/65: write(4, " 1 2 7 . 0 . 0 . 1 - ".., 78) = 78

Bu write(2) çağrısı isteği erişim günlüğüne kaydeder. Bu izlemede eksik olan tek şey, time(2) çağrısıdır. Apache 1.3'ün aksine, Apache 2.x zamana bakmak için gettimeofday(3) çağırısını kullanır. Linux ve Solaris gibi bazı işletim sistemleri, gettimeofday işlevinin, sıradan bir sistem çağrısından daha fazla götürüsü olmayan en iyilenmiş bir gerçeklenimine sahiptir.

/65: shutdown(9, 1, 1) = 0
/65: poll(0xFAF7B980, 1, 2000) = 1
/65: read(9, 0xFAF7BC20, 512) = 0
/65: close(9) = 0

Burada worker evresi bağlantıyı zamana yaymaktadır.

/65: close(10) = 0
/65: lwp_park(0x00000000, 0) (uykuda...)

Son olarak, worker evresi teslim edilen dosyayı kapattıktan sonra dinleyici evre tarafından başka bir bağlantı atanıncaya kadar beklemeye alınır.

/67: accept(3, 0x001FEB74, 0x001FEB94, 1) (uykuda...)

Bu arada, dinleyici evre bağlantıyı bir worker evresine atar atamaz başka bir bağlantıyı beklemeye başlar (Mevcut tüm evreler meşgulse dinleyici evreyi baskılayan worker MPM'nin akış denetim şemasına konu olur). Bu izlemede görünmüyor olsa da sonraki accept(2) çağrısı, yeni bağlantı kabul eden worker evresine paralel olarak yapılabilir (aşırı yük durumlarında normal olarak, bu yapılır).

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Güvenlik İpuçları - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Çeşitli Belgeler

Güvenlik İpuçları

Bir HTTP Sunucusunu ayarlarken dikkat edilmesi gerekenler ve bazı ipuçları. Öneriler kısmen Apache’ye özel kısmen de genel olacaktır.

Güncel Tutma

Apache HTTP Sunucusu iyi bir güvenlik sicilinin yanında güvenlik konularıyla oldukça ilgili bir geliştirici topluluğuna sahiptir. Fakat, bir yazılımın dağıtılmasının ardından küçük ya da büyük bazı sorunların keşfedilmesi kaçınılmazdır. Bu sebeple, yazılım güncellemelerinden haberdar olmak oldukça önem kazanır. HTTP sunucunuzu doğrudan Apache’den temin ediyorsanız yeni sürümler ve güvenlik güncellemeleri ile ilgili bilgileri tam zamanında alabilmek için Apache HTTP Sunucusu Duyuru Listesine mutlaka üye olmanızı öneririz. Apache yazılımının üçüncü parti dağıtımlarını yapanların da buna benzer hizmetleri vardır.

Şüphesiz, bir HTTP sunucusu, sunucu kodunda bir sorun olmasa da tehlike altındadır. Eklenti kodları, CGI betikleri hatta işletim sisteminden kaynaklanan sorunlar nedeniyle bu ortaya çıkabilir. Bu bakımdan, sisteminizdeki tüm yazılımların sorunları ve güncellemeleri hakkında bilgi sahibi olmalısınız.

Hizmet Reddi (DoS) Saldırıları

Tüm ağ sunucuları, istemcilerin sistem kaynaklarından yararlanmalarını engellemeye çalışan hizmet reddi saldırılarına (HRS) maruz kalabilir. Bu tür saldırıları tamamen engellemek mümkün değildir, fakat yarattıkları sorunları azaltmak için bazı şeyler yapabilirsiniz.

Çoğunlukla en etkili anti-HRS aracı bir güvenlik duvarı veya başka bir işletim sistemi yapılandırmasıdır. Örneğin, çoğu güvenlik duvarı herhangi bir IP adresinden aynı anda yapılan bağlantıların sayısına bir sınırlama getirmek üzere yapılandırılabilir. Böylece basit saldırılar engellenebilir. Ancak bunun dağıtık hizmet reddi saldırılarına (DHRS) karşı bir etkisi olmaz.

Bunların yanında Apache HTTP Sunucusunun da sorunları azaltıcı tedbirler alınmasını sağlayacak bazı yapılandırmaları vardır:

  • RequestReadTimeout yönergesi bir istemcinin isteği göndermek için harcadığı zamanı sınırlamayı sağlar.
  • HRS’ye maruz kalması olası sitelerde TimeOut yönergesinin değeri düşürülmelidir. Birkaç saniye gibi mümkün olduğunca düşük bir ayar uygun olabilir. Ancak TimeOut başka işlemlerde de kullanıldığından çok düşük değerler, örneğin, uzun süre çalışan CGI betiklerinde sorunlar çıkmasına sebep olabilir.
  • HRS’ye maruz kalması olası sitelerde KeepAliveTimeout yönergesinin değeri de düşürülebilir. Hatta bazı siteler başarımı arttırmak amacıyla KeepAlive yönergesi üzerinden kalıcı bağlantıları tamamen kapatabilirler.
  • Zaman aşımıyla ilgili yönergeler bakımından diğer modüller de araştırılmalıdır.
  • LimitRequestBody, LimitRequestFields, LimitRequestFieldSize, LimitRequestLine ve LimitXMLRequestBody yönergeleri, istemci girdileri ile tetiklenen özkaynak tüketimini sınırlamak için yapılandırılırken dikkatli olunmalıdır.
  • İşletim sisteminiz desteklediği takdirde, işletim sisteminin isteği işleyen kısmını yüksüz bırakmak için AcceptFilter yönergesinin etkin olmasını sağlamalısınız. Bu, Apache HTTP Sunucusunda zaten öntanımlı olarak etkindir. Yapacağınız şey işletim sistemi çekirdeğini buna göre yapılandırmak olacaktır.
  • Sunucu tarafından özkaynakları tüketmeden aynı anda işlenebilecek bağlantıların sayısını sınırlamak için MaxRequestWorkers yönergesini kullanın. Ayrıca, başarım arttırma belgesine de bakabilirsiniz.
  • HRS’lerin etkilerini azaltmak için aynı andaki bağlantı sayısını arttırabilecek evreli MPM’lerden birini kullanmak iyi olabilir. Dahası, event MPM’i her bağlantıya yeni bir evre atanmaması için eşzamansız işlem yapar. OpenSSL kütüphanesinin doğası nedeniyle event MPM’i mod_ssl ve diğer girdi süzgeçleri ile henüz uyumlu değildir. Bu durumlarda, worker MPM'inin davranışına geri döner.
  • http://modules.apache.org/ adresinde, belli istemci davranışlarını sınırlayacak ve HRS ile ilgili sorunları azaltmaya yardımcı olacak üçüncü parti modüller bulunabilir.

ServerRoot Dizinlerinin İzinleri

Normalde, Apache root kullanıcı tarafından başlatılır ve hizmetleri sunarken User yönergesi tarafından tanımlanan kullanıcının aidiyetinde çalışır. Root tarafından çalıştırılan komutlarda olduğu gibi, root olmayan kullanıcıların yapacakları değişikliklerden korunmak konusunda da dikkatli olmalısınız. Dosyaların sadece root tarafından yazılabilir olmasını sağlamak yeterli değildir, bu dizinler ve üst dizinler için de yapılmalıdır. Örneğin, sunucu kök dizininin /usr/local/apache olmasına karar verdiyseniz, bu dizini root olarak şöyle oluşturmanız önerilir:

mkdir /usr/local/apache
cd /usr/local/apache
mkdir bin conf logs
chown 0 . bin conf logs
chgrp 0 . bin conf logs
chmod 755 . bin conf logs

/, /usr, /usr/local dizinlerinde sadece root tarafından değişiklik yapılabileceği kabul edilir. httpd çalıştırılabilirini kurarken de benzer bir önlemin alındığından emin olmalısınız:

cp httpd /usr/local/apache/bin
chown 0 /usr/local/apache/bin/httpd
chgrp 0 /usr/local/apache/bin/httpd
chmod 511 /usr/local/apache/bin/httpd

Diğer kullanıcıların değişiklik yapabileceği bir dizin olarak bir htdocs dizini oluşturabilirsiniz. Bu dizine root tarafından çalıştırılabilecek dosyalar konulmamalı ve burada root tarafından hiçbir dosya oluşturulmamalıdır.

Diğer kullanıcılara root tarafından yazılabilen ve çalıştırılabilen dosyalarda değişiklik yapma hakkını tanırsanız, onlara root kullanıcısını ele geçirilebilme hakkını da tanımış olursunuz. Örneğin, biri httpd çalıştırılabilirini zararlı bir programla değiştirebilir ve o programı tekrar çalıştırdığınız sırada program yapacağını yapmış olur. Günlükleri kaydettiğiniz dizin herkes tarafından yazılabilen bir dizin olduğu takdirde, birileri bir günlük dosyasını bir sistem dosyasına sembolik bağ haline getirerek root kullanıcısının bu dosyaya ilgisiz şeyler yazmasına sebep olabilir. Günlüklerin dosyaları herkes tarafından yazılabilir olduğu takdirde ise birileri dosyaya yanıltıcı veriler girebilir.

Sunucu Taraflı İçerik Yerleştirme

SSI sayfaları bir sunucu yöneticisi açısından çeşitli olası risklere kaynaklık edebilir.

İlk risk, sunucu yükündeki artış olasılığıdır. Tüm SSI sayfaları, SSI kodu içersin içermesin Apache tarafından çözümlenir. Bu küçük bir artış gibi görünürse de bir paylaşımlı sunucu ortamında önemli bir yük haline gelebilir.

SSI sayfaları, CGI betikleriyle ilgili riskleri de taşır. exec cmd elemanı kullanılarak bir SSI sayfasından herhangi bir CGI betiğini veya bir sistem programını Apache’nin aidiyetinde olduğu kullanıcının yetkisiyle çalıştırmak mümkündür.

SSI sayfalarının yararlı özelliklerinden yararlanırken güvenliğini de arttırmanın bazı yolları vardır.

Sunucu yöneticisi, bir başıbozuk SSI sayfasının sebep olabileceği zararları bertaraf etmek için CGI Genelinde bölümünde açıklandığı gibi suexec’i etkin kılabilir.

SSI sayfalarını .html veya .htm uzantılarıyla etkinleştirmek tehlikeli olabilir. Bu özellikle paylaşımlı ve yüksek trafikli bir sunucu ortamında önemlidir. SSI sayfalarını normal sayfalardan farklı olarak .shtml gibi bildik bir uzantıyla etkinleştirmek gerekir. Bu, sunucu yükünü asgari düzeyde tutmaya ve risk yönetimini kolaylaştırmaya yarar.

Diğer bir çözüm de SSI sayfalarından betik ve program çalıştırmayı iptal etmektir. Bu, Options yönergesine değer olarak Includes yerine IncludesNOEXEC vererek sağlanır. Ancak, eğer betiklerin bulunduğu dizinde ScriptAlias yönergesiyle CGI betiklerinin çalışması mümkün kılınmışsa, kullanıcıların <--#include virtual="..." --> ile bu betikleri çalıştırabileceklerine dikkat ediniz.

CGI Genelinde

Herşeyden önce ya CGI betiğini/programını yazanlara ya da kendinizin CGI'deki güvenlik açıklarını (ister kasıtlı olsun ister tesadüfi) yakalama becerinize güvenmek zorundasınız. CGI betikleri esasen sisteminizdeki komutları site kullanıcılarının izinleriyle çalıştırırlar. Bu bakımdan dikkatle denenmedikleri takdirde oldukça tehlikeli olabilirler.

CGI betiklerinin hepsi aynı kullanıcının aidiyetinde çalışırsa diğer betiklerle aralarında çelişkilerin ortaya çıkması ister istemez kaçınılmazdır. Örneğin A kullanıcısının B kullanıcısına garezi varsa bir betik yazıp B’nin CGI veritabanını silebilir. Bu gibi durumların ortaya çıkmaması için betiklerin farklı kullanıcıların aidiyetlerinde çalışmasını sağlayan ve 1.2 sürümünden beri Apache ile dağıtılan suEXEC diye bir program vardır. Başka bir yol da CGIWrap kullanmaktır.

ScriptAlias’sız CGI

Kullanıcıların sitenin her yerinde CGI betiklerini çalıştırmalarına izin vermek ancak şu koşullarda mümkün olabilir:

  • Kullanıcılarınızın kasıtlı ya da kasıtsız sistemi saldırıya açık hale getirecek betikler yazmayacaklarına tam güveniniz vardır.
  • Sitenizin güvenliği zaten o kadar kötüdür ki, bir delik daha açılmasının mahzuru yoktur.
  • Sitenizin sizden başka kullanıcısı yoktur ve sunucunuzu sizden başka hiç kimsenin ziyaret etmesi mümkün değildir.

ScriptAlias’lı CGI

CGI’yi belli dizinlerle sınırlamak yöneticiye bu dizinlerde daha iyi denetim imkanı sağlar. Bu kaçınılmaz olarak ScriptAlias’sız CGI’den çok daha güvenlidir, ancak bu dizinlere yazma hakkı olan kullanıcılarınız güvenilir kişiler olması ve site yöneticisinin de olası güvenlik açıklarına karşı CGI betiklerini ve programlarını denemeye istekli olması şartıyla.

Çoğu site yöneticisi ScriptAlias’sız CGI yerine bu yaklaşımı seçer.

Devingen içerikli kaynaklar

Sunucunun bir parçası gibi çalışan, mod_php, mod_perl, mod_tcl ve mod_python gibi gömülü betik çalıştırma seçenekleri sunucuyu çalıştıran kullanıcının aidiyetinde çalışırlar (User yönergesine bakınız). Bu bakımdan bu betik yorumlayıcılar tarafından çalıştırılan betikler, sunucu kullanıcısının eriştiği herşeye erişebilirler. Bazı betik yorumlayıcıların getirdiği bazı sınırlamalar varsa da bunlara pek güvenmemek, gerekli sınamaları yine de yapmak gerekir.

Devingen içeriğin güvenliği

mod_php, mod_perl veya mod_python gibi devingen içeriği yapılandırırken güvenlikle ilgili değerlendirmelerin çoğu httpd'nin kapsamından çıkar ve bu modüllerin belgelerini incelemek ihtiyacı duyarsınız. Örneğin, PHP çoğu zaman kapalı tutulan Güvenli Kip ayarını etkin kılmanızı önerir. Daha fazla güvenlik için bir diğer örnek bir PHP eklentisi olan Suhosin'dir. Bunlar hakkında daha ayrıntılı bilgi için her projenin kendi belgelerine başvurun.

Apache seviyesinde, mod_security adı verilen modülü bir HTTP güvenlik duvarı gibi ele alabilir, devingen içeriğin güvenliğini arttırmanıza yardımcı olmak üzere inceden inceye yapılandırabilirsiniz.

Sistem Ayarlarının Korunması

Güvenliği gerçekten sıkı tutmak istiyorsanız, kullanıcılarınızın yapılandırmanızdaki güvenlik ayarlarını geçersiz kılmak için .htaccess dosyalarını kullanabilmelerinin de önüne geçmelisiniz. Bunu yapmanın tek bir yolu vardır.

Sunucu yapılandırma dosyanıza şunu yerleştirin:

<Directory "/">
    AllowOverride None
</Directory>

Böylece, belli dizinlerde özellikle etkinleştirilmedikçe bütün dizinlerde .htaccess dosyalarının kullanımını engellemiş olursunuz.

Bu ayar Apache 2.3.9 itibariyle öntanımlıdır.

Sunucu dosyalarının öntanımlı olarak korunması

Apache’nin ister istemez yanlış anlaşılan yönlerinden biri öntanımlı erişim özelliğidir. Yani siz aksine bir şeyler yapmadıkça, sunucu normal URL eşleme kurallarını kullanarak bir dosyayı bulabildiği sürece onu istemciye sunacaktır.

Örneğin, aşağıdaki durumu ele alalım:

# cd /; ln -s / public_html

Ve, tarayıcınıza http://localhost/~root/ yazın.

Böylece, istemcilerin tüm dosya sisteminizi gezmelerine izin vermiş olursunuz. Bu işlemin sonuçlarının önünü almak için sunucu yapılandırma dosyanıza şunları yazın:

<Directory "/">
    Require all denied
</Directory>

Bu suretle, dosya sisteminize öntanımlı erişimi yasaklamış olursunuz. Erişime izin vermek istediğiniz dizinler için uygun Directory bölümleri eklemeniz yeterli olacaktır. Örnek:

<Directory "/usr/users/*/public_html">
    Require all granted
</Directory>
<Directory "/usr/local/httpd">
    Require all granted
</Directory>

Location ve Directory yönergelerinin etkileşimine de özellikle önem vermelisiniz; örneğin <Directory "/"> erişimi yasaklarken bir <Location "/"> yönergesi bunu ortadan kaldırabilir.

UserDir yönergesi de size buna benzer bir oyun oynayabilir; yönergeye ./ atamasını yaparsanız, root kullanıcısı söz konusu olduğunda yukarıda ilk örnekteki durumla karşılaşırız. Sunucu yapılandırma dosyanızda aşağıdaki satırın mutlaka bulunmasını öneririz:

UserDir disabled root

Günlüklerin İzlenmesi

Sunucunuzda olup biteni günü gününe bilmek istiyorsanız günlük dosyalarına bakmalısınız. Günlük dosyaları sadece olup biteni raporlamakla kalmaz, sunucunuza ne tür saldırılar yapıldığını ve güvenlik seviyenizin yeterli olup olmadığını anlamanızı da sağlarlar.

Bazı örnekler:

grep -c "/jsp/source.jsp?/jsp/ /jsp/source.jsp??" access_log
grep "client denied" error_log | tail -n 10

İlk örnek, Apache Tomcat Source.JSP Bozuk İstek Bilgilerini İfşa Açığını istismar etmeyi deneyen saldırıların sayısını verirken ikinci örnek, reddedilen son on istemciyi listeler; örnek:

[Thu Jul 11 17:18:39 2002] [error] [client foo.example.com] client denied by server configuration: /usr/local/apache/htdocs/.htpasswd

Gördüğünüz gibi günlük dosyaları sadece ne olup bittiğini raporlar, bu bakımdan eğer istemci .htpasswd dosyasına erişebiliyorsa erişim günlüğünüzde şuna benzer bir kayıt görürsünüz:

foo.example.com - - [12/Jul/2002:01:59:13 +0200] "GET /.htpasswd HTTP/1.1"

Bu, sunucu yapılandırma dosyanızda aşağıdaki yapılandırmayı iptal ettiğiniz anlamına gelir:

<Files ".ht*">
    Require all denied
</Files>

Yapılandırma bölümlerinin birleştirilmesi

Yapılandırma bölümlerinin birleştirilmesi karmaşık bir işlem olup bazı durumlarda yönergelere bağlıdır. Yönergeleri bir araya getirirken aralarındaki bağımlılıkları daima sınayın.

mod_access_compat gibi henüz yönerge katıştırma mantığını gerçeklememiş modüller için sonraki bölümlerdeki davranış, bu modüllerin yönergelerini içerip içermemesine bağlıdır. Yapılandırmada yönergelerin yerleri değiştirildiğinde fakat bir katıştırma yapılmadığında, yapılandırma bir değişiklik yapılana kadar miras alınır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Relevant Standards - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Miscellaneous Documentation

Relevant Standards

This page documents all the relevant standards that the Apache HTTP Server follows, along with brief descriptions.

In addition to the information listed below, the following resources should be consulted:

  • http://purl.org/NET/http-errata - HTTP/1.1 Specification Errata
  • http://www.rfc-editor.org/errata.php - RFC Errata
  • http://ftp.ics.uci.edu/pub/ietf/http/#RFC - A pre-compiled list of HTTP related RFCs

Notice

This document is not yet complete.

HTTP Recommendations

Regardless of what modules are compiled and used, Apache as a basic web server complies with the following IETF recommendations:

RFC 1945 (Informational)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. This documents HTTP/1.0.
RFC 2616 (Standards Track)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This documents HTTP/1.1.
RFC 2396 (Standards Track)
A Uniform Resource Identifier (URI) is a compact string of characters for identifying an abstract or physical resource.
RFC 4346 (Standards Track)
The TLS protocol provides communications security over the Internet. It provides encryption, and is designed to prevent eavesdropping, tampering, and message forgery.

HTML Recommendations

Regarding the Hypertext Markup Language, Apache complies with the following IETF and W3C recommendations:

RFC 2854 (Informational)
This document summarizes the history of HTML development, and defines the "text/html" MIME type by pointing to the relevant W3C recommendations.
HTML 4.01 Specification (Errata)
This specification defines the HyperText Markup Language (HTML), the publishing language of the World Wide Web. This specification defines HTML 4.01, which is a subversion of HTML 4.
HTML 3.2 Reference Specification
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents.
XHTML 1.1 - Module-based XHTML (Errata)
This Recommendation defines a new XHTML document type that is based upon the module framework and modules defined in Modularization of XHTML.
XHTML 1.0 The Extensible HyperText Markup Language (Second Edition) (Errata)
This specification defines the Second Edition of XHTML 1.0, a reformulation of HTML 4 as an XML 1.0 application, and three DTDs corresponding to the ones defined by HTML 4.

Authentication

Concerning the different methods of authentication, Apache follows the following IETF recommendations:

RFC 2617 (Standards Track)
"HTTP/1.0", includes the specification for a Basic Access Authentication scheme.

Language/Country Codes

The following links document ISO and other language and country code information:

ISO 639-2
ISO 639 provides two sets of language codes, one as a two-letter code set (639-1) and another as a three-letter code set (this part of ISO 639) for the representation of names of languages.
ISO 3166-1
These pages document the country names (official short names in English) in alphabetical order as given in ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 code elements.
BCP 47 (Best Current Practice), RFC 3066
This document describes a language tag for use in cases where it is desired to indicate the language used in an information object, how to register values for use in this language tag, and a construct for matching such language tags.
RFC 3282 (Standards Track)
This document defines a "Content-language:" header, for use in cases where one desires to indicate the language of something that has RFC 822-like headers, like MIME body parts or Web documents, and an "Accept-Language:" header for use in cases where one wishes to indicate one's preferences with regard to language.


Password Formats - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Miscellaneous Documentation

Password Formats

Notes about the password encryption formats generated and understood by Apache.

Basic Authentication

There are five formats that Apache recognizes for basic-authentication passwords. Note that not all formats work on every platform:

bcrypt
"$2y$" + the result of the crypt_blowfish algorithm. See the APR source file crypt_blowfish.c for the details of the algorithm.
MD5
"$apr1$" + the result of an Apache-specific algorithm using an iterated (1,000 times) MD5 digest of various combinations of a random 32-bit salt and the password. See the APR source file apr_md5.c for the details of the algorithm.
SHA1
"{SHA}" + Base64-encoded SHA-1 digest of the password. Insecure.
CRYPT
Unix only. Uses the traditional Unix crypt(3) function with a randomly-generated 32-bit salt (only 12 bits used) and the first 8 characters of the password. Insecure.
PLAIN TEXT (i.e. unencrypted)
Windows & Netware only. Insecure.

Generating values with htpasswd

bcrypt

$ htpasswd -nbB myName myPassword
myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC

MD5

$ htpasswd -nbm myName myPassword
myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

SHA1

$ htpasswd -nbs myName myPassword
myName:{SHA}VBPuJHI7uixaa6LQGWx4s+5GKNE=

CRYPT

$ htpasswd -nbd myName myPassword
myName:rqXexS6ZhobKA

Generating CRYPT and MD5 values with the OpenSSL command-line program

OpenSSL knows the Apache-specific MD5 algorithm.

MD5

$ openssl passwd -apr1 myPassword
$apr1$qHDFfhPC$nITSVHgYbDAK1Y0acGRnY0

CRYPT

openssl passwd -crypt myPassword
qQ5vTYO3c8dsU

Validating CRYPT or MD5 passwords with the OpenSSL command line program

The salt for a CRYPT password is the first two characters (converted to a binary value). To validate myPassword against rqXexS6ZhobKA

CRYPT

$ openssl passwd -crypt -salt rq myPassword
Warning: truncating password to 8 characters
rqXexS6ZhobKA

Note that using myPasswo instead of myPassword will produce the same result because only the first 8 characters of CRYPT passwords are considered.

The salt for an MD5 password is between $apr1$ and the following $ (as a Base64-encoded binary value - max 8 chars). To validate myPassword against $apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

MD5

$ openssl passwd -apr1 -salt r31..... myPassword
$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

Database password fields for mod_dbd

The SHA1 variant is probably the most useful format for DBD authentication. Since the SHA1 and Base64 functions are commonly available, other software can populate a database with encrypted passwords that are usable by Apache basic authentication.

To create Apache SHA1-variant basic-authentication passwords in various languages:

PHP

'{SHA}' . base64_encode(sha1($password, TRUE))

Java

"{SHA}" + new sun.misc.BASE64Encoder().encode(java.security.MessageDigest.getInstance("SHA1").digest(password.getBytes()))

ColdFusion

"{SHA}" & ToBase64(BinaryDecode(Hash(password, "SHA1"), "Hex"))

Ruby

require 'digest/sha1'
require 'base64'
'{SHA}' + Base64.encode64(Digest::SHA1.digest(password))

C or C++

Use the APR function: apr_sha1_base64

Python

import base64
import hashlib
"{SHA}" + format(base64.b64encode(hashlib.sha1(password).digest()))

PostgreSQL (with the contrib/pgcrypto functions installed)

'{SHA}'||encode(digest(password,'sha1'),'base64')

Digest Authentication

Apache recognizes one format for digest-authentication passwords - the MD5 hash of the string user:realm:password as a 32-character string of hexadecimal digits. realm is the Authorization Realm argument to the AuthName directive in httpd.conf.

Database password fields for mod_dbd

Since the MD5 function is commonly available, other software can populate a database with encrypted passwords that are usable by Apache digest authentication.

To create Apache digest-authentication passwords in various languages:

PHP

md5($user . ':' . $realm . ':' .$password)

Java

      byte b[] = java.security.MessageDigest.getInstance("MD5").digest( (user + ":" + realm + ":" + password ).getBytes());
java.math.BigInteger bi = new java.math.BigInteger(1, b);
String s = bi.toString(16);
while (s.length() < 32)
s = "0" + s;

      // String s is the encrypted password

ColdFusion

LCase(Hash( (user & ":" & realm & ":" & password) , "MD5"))

Ruby

require 'digest/md5'
Digest::MD5.hexdigest(user + ':' + realm + ':' + password)

PostgreSQL (with the contrib/pgcrypto functions installed)

encode(digest( user || ':' || realm || ':' || password , 'md5'), 'hex')


Modülleri Tanımlamakta Kullanılan Terimler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Modülleri Tanımlamakta Kullanılan Terimler

Bu belgede Apache modüllerini tanımlarken kullanılan terimler açıklanmıştır.

Açıklama

Modülün kullanım amacının kısa bir açıklaması.

Durum

Modülün Apache HTTP sunucusuna ne kadar sıkı bağlı olduğunu belirtir. Başka bir deyişle, modüle ve işlevselliğine erişim kazanmak için sunucuyu yeniden derlemek gerekip gerekmediği ile ilgili durumu belirtir. Bu özniteliğin olası değerleri şunlardır:

MPM
“MPM” durumlu bir modül bir Çok Süreçlilik Modülüdür. Diğer modül türlerinin aksine, sunucunun kullandığı MPM modülü sayısı birden fazla olamaz. Bu modül türü temelde sunucuya gelen isteklerin ele alınmasından ve öldürülmesinden sorumludur.
Temel
“Temel” durumuyla etiketlenmiş bir modül öntanımlı olarak olarak derlenir ve sunucuya öntanımlı olarak yüklenir. Bu bakımdan derleme öncesi paket yapılandırması sırasında modülün derlenmemesi özellikle istenmedikçe bu modül derlenecek ve sunucuya yüklenecektir.
Eklenti
“Eklenti” durumundaki bir modül normal olarak derlenmez ve sunucuya yüklenmez. Modülü ve işlevselliğini etkin kılmak için sunucunun derleme öncesi paket yapılandırması sırasında modülün derleneceğini açıkça belirttikten sonra gerekirse yeniden derlemeniz gerekir.
Deneysel
“Deneysel” durumu modülün Apache sunucusunun bir parçası olarak kabul edildiğini ancak modülü denemenin tamamen sizin insiyatifinize bırakıldığı anlamına gelir. Böyle bir modül her şeyiyle belgelenmiştir fakat gerektiği gibi desteklenmemiştir.
Harici
“Harici” durumu temel Apache dağıtımında bulunmayan (“üçüncü parti”) modüller için kullanılır. Böyle modüller için sorumluluk kabul etmediğimiz gibi bunları desteklemiyoruz.

Kaynak Dosyası

Karşısına modül kodunu içeren kaynak dosyasının ismi yazılır. Bu isim ayrıca <IfModule> yönergesi tarafından da kullanılır.

Modül Betimleyici

Modüller devingen olarak yüklenirken LoadModule yönergesinde kullanmak için modülü betimleyen dizgedir. Aslında, kaynak dosyasında module türündeki harici değişkenin ismidir.

Uyumluluk

Eğer modül Apache’nin 2. sürüm dağıtımının özgün parçası değilse söz konusu sürüm burada belirtilir. Ayrıca, modülün kullanımı belli platformlarla sınırlıysa bunun ayrıntıları da burada belirtilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Yönergeleri Tanımlamakta Kullanılan Terimler - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Yönergeleri Tanımlamakta Kullanılan Terimler

Bu belgede Apache yapılandırma yönergelerini tanımlamakta kullanılan terimler açıklanmıştır.

Ayrıca bakınız:

  • Yapılandırma dosyaları

Açıklama

Yönergenin kullanım amacının kısa bir açıklaması.

Sözdizimi

Yönergenin bir yapılandırma dosyasında hangi söz dizimiyle görünebileceği belirtilir. Bu sözdizimi yönergeye özeldir ve ayrıntıları yönerge tanımında açıklanır. Genelde yönerge ismini aralarında boşluklar bırakılmış bir dizi argüman izler. Eğer argümanlardan biri kendi içinde boşluk içeriyorsa çift tırnak içine alınır. İsteğe bağlı argümanlar sözdiziminde köşeli ayraçların arasında gösterilmiştir. Birden fazla olası değeri olan argümanlarda değerler aralarına | karakteri konarak ayrılmıştır. Değerin yerine ismi belirtilen argümanlarda bu isimler eğik yazılırken, kendisi değer olan dizgeler öntanımlı yazıtipi ile gösterilmiştir. Değişik sayıda argüman alan yönergelerde bu durum son argümanı takibeden “...” ile belirtilmiştir.

Yönergelerde kullanılan argüman türleri çok çeşitlidir. Çok kullanılanlardan bazıları aşağıda tanımlanmıştır.

URL
http://host.example.com/yol/yordam/dosya.html örneğindeki gibi protokol şeması ve konak ismini isteğe bağlı bir dosya yolunun izlediği, açılımı “Uniform Resource Locator” olan ve Türkçe’ye “Tektip Özkaynak Konumlayıcı” şeklinde çevrilebilecek adresleri betimler.
URL-yolu
/yol/yordam/dosya.html örneğindeki gibi bir url’nin parçası olarak protokol şeması ve konak ismini izleyen bir yol dizgesini betimler. url-yolu, bir dosya sisteminin kök dizinine göre değil, DocumentRoot ile belirtilen dizine göre bir dosya yolu betimler.
dosya-yolu
/usr/local/apache/htdocs/yol/yordam/dosya.html örneğindeki gibi yerel dosya sisteminin kök dizini ile başlayan bir dosya yolunu betimler. Aksi belirtilmedikçe, bir / ile başlamayan bir dosya-yolu ServerRoot ile belirtilen dizine göre ele alınır.
dizin-yolu
/usr/local/apache/htdocs/yol/yordam/ örneğindeki gibi kök dizin ile başlayan, yerel dosya sistemindeki bir dizin yolunu betimler.
dosya-ismi
dosya.html örneğindeki gibi dizin yolu içermeyen bir dosya ismini betimler.
düzifd
Bir Perl uyumlu düzenli ifade betimler. Yönerge tanımında düzifd ile eşleşenler argüman olarak ele alınır.
uzantı
Bu genelde, dosya-ismi’nin bir parçası olarak son noktadan sonraki kısmı betimler. Bununla birlikte, Apache çok sayıda nokta içeren dosya isimlerinde ilk noktadan sonrasını uzantı kabul eden çoklu dosya ismi uzantılarını da tanır. Örneğin, dosya- ismi olarak dosya.html.tr değeri iki uzantı içerir: .html ve .tr. Apache yönergelerinde uzantı’ları başında noktası olmaksızın da belirtebilirsiniz. Ayrıca, uzantı’lar harf büyüklüğüne de duyarlı değildir.
MIME-türü
Dosya biçiminin, text/html örneğindeki gibi aralarına bir / konulmuş asıl ve alt biçimler şeklinde açıklandığı yönteme göre belirtileceğini betimler.
ortam-değişkeni
Apache yapılandırma sürecinde tanımlanmış bir ortam değişkeninin ismini betimler. Daha ayrıntılı bilgi için ortam değişkenleri belgesine bakınız.

Öntanımlı

Eğer yönerge öntanımlı bir değere sahipse o burada belirtilir (öntanımlı değer, yönergede kullanıcı tarafından belirtilmediği halde Apache tarafından belirtildiği varsayılarak işlem yapılan değerdir). Eğer öntanımlı bir değer yoksa bu bölümde bu durum “Yok” şeklinde belirtilir. Burada belirtilen öntanımlı değerin sunucu ile dağıtılan öntanımlı httpd.conf içindeki yönergede kullanılan değerle aynı olmasının gerekmediğine dikkat ediniz.

Bağlam

Yönergenin sunucunun yapılandırma dosyalarının nerelerinde meşru kabul edildiği aşağıdaki değerlerin virgül ayraçlı bir listesi halinde burada belirtilir.

sunucu geneli
Yönergenin sunucunun (httpd.conf gibi) yapılandırma dosyalarında <VirtualHost> ve <Directory> bölümleri dışında her yerde kullanılabileceğini belirtir. Ayrıca, .htaccess dosyalarında bulunmasına da izin verilmez.
sanal konak
Yönergenin sunucunun yapılandırma dosyalarının sadece <VirtualHost> bölümlerinde kullanıldığında geçerli kabul edileceğini belirtir.
dizin
Yönergenin sunucunun yapılandırma dosyalarında sadece <Directory>, <Location>, <Files>, <If> ve <Proxy> bölümlerinde kullanıldığında geçerli kabul edileceğini belirtir. Bu bağlama konu sınırlamaların çerçevesi Yapılandırma Bölümleri içinde çizilmiştir.
.htaccess
Bu bağlamda geçerli olacağı kabul edilen bir yönerge sadece dizin içi .htaccess dosyalarında görüldüğü zaman işleme sokulur. Üzerinde bir geçersizleştirme etkin kılınmışsa yönerge her şeye rağmen işleme sokulmayabilir.

Yönergeye sadece tasarlandığı bağlam içinde izin verilir; başka bir yerde kullanmayı denerseniz ya sunucunun bu bağlamı doğru şekilde işlemesine engel olan ya da sunucunun tamamen işlevsiz kalmasına sebep olan -- sunucu hiç başlatılamayabilir -- bir yapılandırma hatası alırsınız.

Yönergenin geçerli olacağı konumlar, aslında, listelenen bağlamların tamamına mantıksal VEYA uygulanarak bulunur. Başka bir deyişle, bir yönergenin geçerli olacağı yerler "sunucu geneli, .htaccess" şeklinde belirtilmişse yönerge httpd.conf dosyasında ve .htaccess dosyalarında, <Directory> veya <VirtualHost> bölümleri haricinde her yerde kullanılabilir.

Geçersizleştirme

Bir .htaccess dosyasında göründüğü takdirde yönerge işlenirken hangi yapılandırma geçersizleşirmesinin etkin olacağı burada belirtilir. Eğer yönerge bağlamının .htaccess dosyalarında görünmesine izin verilmiyorsa hiçbir bağlam listelenmez.

Geçersizleştirmeler AllowOverride yönergesi tarafından etkinleştirilir ve belli bir bağlama ve alt seviyelerde başka AllowOverride yönergeleri ile değiştirilmedikçe tüm çocuklarına uygulanır. Yönergenin belgesinde ayrıca kullanılabilecek tüm olası geçersizleştirme isimleri belirtilir.

Durum

Yönergenin Apache HTTP sunucusuna ne kadar sıkı bağlı olduğunu belirtir. Başka bir deyişle, yönergeye ve işlevselliğine erişim kazanmak için sunucuyu belli bir modül kümesiyle yeniden derlemek gerekip gerekmediği ile ilgili durumu belirtir. Bu özniteliğin olası değerleri şunlardır:

Çekirdek
Eğer bir yönerge “Çekirdek” durumuna sahip olarak listelenmişse bu, yönergenin Apache HTTP sunucusunun en iç kısımlarının bir parçası olduğu ve daima kullanılabilir olacağı anlamına gelir.
MPM
“MPM” durumuna sahip bir yönerge Çok Süreklilik Modülü tarafından sağlanır. Bu yönerge türü sadece ve sadece yönerge tanımının Modül satırında listelenmiş MPM’lerden birini kullanıyorsanız mevcut olacaktır.
Temel
“Temel” durumuna sahip bir yönerge, sunucuda öntanımlı derlenmiş standart Apache modüllerinden biri tarafından destekleniyor demektir. Bu nedenle sunucuyu derlemek için yapılandırırken yönergeyi içeren modülü yapılandırmadan özellikle kaldırmazsanız yönerge normal olarak kullanılabilir olacaktır.
Eklenti
“Eklenti” durumuna sahip bir yönerge, Apache sunucu kitinde bulunan ancak normalde sunucuyla birlikte derlenmeyen modüllerden biri tarafından sağlanır. Yönergeyi ve işlevselliğini etkin kılmak için sunucunun derleme öncesi paket yapılandırması sırasında modülün derleneceğini açıkça belirttikten sonra gerekirse sunucuyu yeniden derlemeniz gerekir.
Deneysel
“Deneysel” durumuna sahip bir yönerge, Apache sunucu kitinde bulunan modüllerden biri tarafından sağlanır ve modülün denenmesi tamamen sizin insiyatifinize bırakılır. Böyle bir yönerge her şeyiyle belgelenmiştir fakat gerektiği gibi desteklenmemiştir. Yönergeyi içeren modül öntanımlı olarak sunucuyla birlikte derlenebileceği gibi derlenmeyebilir de; bunun için yönergenin açıklandığı sayfanın başına ve kullanılabilirliği hakkında bilgi edinmek için yönergeyi içeren modüle bakın.

Modül

Burada sadece yönergeyi tanımlayan kaynak modülün ismi yazılır.

Uyumluluk

Eğer yönerge Apache’nin 2. sürüm dağıtımının özgün parçası değilse söz konusu sürüm burada belirtilir. Ayrıca, yönergenin kullanımı belli platformlarla sınırlıysa bunun ayrıntıları da burada belirtilir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


core - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Temel Özellikleri

Bu çeviri güncel olmayabilir. Son değişiklikler için İngilizce sürüm geçerlidir.
Açıklama: | Apache HTTP Sunucusunda daima mevcut olan çekirdek özellikler
Durum: | Çekirdek

AcceptFilter Yönergesi

Açıklama: | Bir protokolün dinleyici soketleri için en iyilemeleri ayarlar
Sözdizimi: | AcceptFilter protocol kabul_süzgeci
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

Bu yönerge Protocol yönergesinde belirtilen protokol türüne göre bir dinleme soketinin işletim sistemine özgü en iyilemelerini etkin kılar. İşletim sistemi çekirdeği için temel önerme veri alınıncaya kadar veya HTTP isteğinin tamamı tamponlanana kadar sunucu sürecine bir soket tahsis etmemektir. Şimdilik sadece FreeBSD’nin Kabul Süzgeçleri ve Linux’un soket seçeneklerinden TCP_DEFER_ACCEPT ve Windows'un en iyilenmiş AcceptEx() işlevi desteklenmektedir.

Değiştirge olarak none kullanımı, protokolün kabul süzgeçlerini iptal edecektir. ftp: veya nntp gibi sunucunun baştan bir veri göndermesinin gerekli olduğu protokoller için kullanışlıdır. Örnek:

AcceptFilter nntp none

Öntanımlı protokol isimleri port 443 için https ve tüm diğer portlar için http'dir. Dinlenmesi için başka bir port ile ilgili bir protokol belirtmek isterseniz Listen yönergesine protokol argümanını ekleyin.

FreeBSD için öntanımlı değerler:

AcceptFilter http httpready
AcceptFilter https dataready

httpready kabul süzgeci HTTP isteklerinin tamamını işletim sistemi çekirdeği seviyesinde tamponlar. Çekirdek isteğin tamamını alır almaz sunucuya gönderir. Ayrıntılar için accf_http(9) kılavuz sayfasına bakınız. HTTPS istekleri şifrelenmiş olduğundan sadece accf_data(9) süzgeci kullanılır.

Linux’taki öntanımlı değerler:

AcceptFilter http data
AcceptFilter https data

Linux’un TCP_DEFER_ACCEPT soket seçeneği HTTP isteklerinin tamponlanmasını desteklemez. none dahil her değer dinleyici üzerinde TCP_DEFER_ACCEPT seçeneğini etkin kılar. Daha ayrıntılı bilgi edinmek için Linux tcp(7) kılavuz sayfasına bakınız.

Windows’taki öntanımlı değerler::

AcceptFilter http data
AcceptFilter https data

Windows'un mpm_winnt modülü AcceptEx() arayüzünü açıp kapamak için AcceptFilter'i yorumlar ve http protokol tamponlamasını desteklemez. Windows AcceptEx() arayüzünü tetikleyen iki değer vardır ve ağ soketlerini bağlantılar arasında yer değiştirirler. data, veri aktarılana kadar yukarıda anlatıldığı gibi bekler ve ilk veri tamponu ve uç ağ adresleri tek bir AcceptEx() çağrısından alınır. connect, AcceptEx() arayüzünü kullanacak, ayrıca uç ağ adresleri de alınacak, fakat none gibi connect seçeneği de ilk veri aktarımını beklemeyecektir.

Windows'ta none AcceptEx()'ten ziyade accept() kullanır ve ağ soketlerini bağlantılar arasında yer değiştirmez. Sürücü desteği bozuk ağ bağdaştırıcılarından başka vpn sürücüleri gibi bazı sanal ağ sağlayıcılar veya spam, virus veya casus yazılım süzgeçleri için kullanışlıdır.

Ayrıca bakınız:

  • Protocol

AcceptPathInfo Yönergesi

Açıklama: | Dosya isminden sonra belirtilen yol verisini kabul veya reddeder.
Sözdizimi: | AcceptPathInfo On|Off|Default
Öntanımlı: | AcceptPathInfo Default
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core

Bu yönerge, istekte dosya isminden sonra (dizinde belirtilen dosya bulunmayabilir) belirtilen yol verisinin kabul edilip edilmeyeceğini denetler. Dosya isminden sonra belirtilen yol verisi PATH_INFO ortam değişkeninde betiklerin kullanımına sunulabilir.

Örneğin, içinde sadece here.html dosyası bulunan bir /test/ dizinimiz olsun. /test/here.html/more ve /test/nothere.html/more isteklerinin her ikisi de PATH_INFO değişkenine /more verisinin atanmasını sağlar.

AcceptPathInfo yönergesine atanabilecek argüman sayısı üçtür:

Off
Sadece dosya isminden sonra yol verisi bulunmayan istekler kabul edilir. Yukarıdaki örnekteki gibi /test/here.html/more şeklindeki istekler bir 404 (Nesne bulunamadı) hatasıyla sonuçlanır.
On
Mevcut bir dosyaya ait bir dosya isminden sonra bir yol verisinin de belirtildiği istekler kabul edilir. Yukarıdaki örnekteki gibi /test/here.html/more şeklindeki istekler, /test/here.html geçerli bir dosya olduğu takdirde kabul edilir.
Default
Dosya isminden sonra yol verisi belirtilen isteklerin nasıl ele alınacağı istekten sorumlu eylemci tarafından saptanır. Normal dosyalar için çekirdek eylemci öntanımlı olarak PATH_INFO isteklerini reddeder. cgi-script ve isapi-handler gibi betiklere hizmet eden eylemciler ise genellikle PATH_INFO isteklerini öntanımlı olarak kabul ederler.

AcceptPathInfo yönergesinin birincil amacı eylemcinin PATH_INFO istekleri hakkında verdiği kabul veya red kararını geçersiz kılabilmenizi sağlamaktır. Örneğin, PATH_INFO’ya dayalı olarak içerik üretmek için INCLUDES gibi bir süzgeç kullandığınız takdirde bu geçersizleştirme zorunlu olur. Normal dosyalar için çekirdek eylemci normal olarak isteği reddederdi, böyle bir durumda bir betiği etkin kılmak için aşağıdaki gibi bir yapılandırma kullanabilirsiniz:

<Files "mypaths.shtml">
  Options +Includes
  SetOutputFilter INCLUDES
  AcceptPathInfo On
</Files>

AccessFileName Yönergesi

Açıklama: | Dağıtık yapılandırma dosyasının ismi belirtilir.
Sözdizimi: | AccessFileName filename [filename] ...
Öntanımlı: | AccessFileName .htaccess
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Belge yolu üzerindeki dizinlerde dağıtık yapılandırma dosyalarının bulunmasına izin verilmişse sunucu bir isteği işlerken önce bu dizinlerde bu yönergede belirtilmiş yapılandırma dosyasını arar. Örnek:

AccessFileName .acl

Sunucu, /usr/local/web/index.html belgesini döndürmeden önce,

<Directory "/">
    AllowOverride None
</Directory>

şeklinde bir yapılandırma ile iptal edilmiş olmadıkça yönergeler için /.acl, /usr/.acl, /usr/local/.acl ve /usr/local/web/.acl dosyalarını okur.

Ayrıca bakınız:

  • AllowOverride
  • Yapılandırma Dosyaları
  • .htaccess Dosyaları

AddDefaultCharset Yönergesi

Açıklama: | Bir yanıtın içerik türü text/plain veya text/html olduğunda eklenecek öntanımlı karakter kümesi parametresini belirler.
Sözdizimi: | AddDefaultCharset On|Off|karküm
Öntanımlı: | AddDefaultCharset Off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core

Bu yönerge, yanıtın içerik türü text/plain veya text/html olmak şartıyla yanıta eklenecek karakter kümesini (karakter kodlamasınının ismini) belirler. Bu, asıl davranış çoğunlukla kullanıcının istemci yapılandırmasına bağlı olmakla birlikte, yanıtın gövdesinde META elemanı vasıtasıyla belirtilmiş karakter kümesini geçersiz kılar. AddDefaultCharset Off şeklinde bir atama bu işlevselliği iptal eder. AddDefaultCharset On ile bu işlevsellik etkin kılınmaktan başka iso-8859-1 karakter kümesini öntanımlı olarak yanıta eklenir. Yönergede karküm olarak belirtilecek değerler, Genel Ağ ortam türlerinde (MIME türlerinde) kullanmak üzere IANA’da kayıtlı karakter kümesi değerlerinden biri olmalıdır. Örnek:

AddDefaultCharset utf-8

AddDefaultCharset yönergesi sadece, metin kaynaklarının hepsinin aynı karakter kümesine sahip olduğu bilindiği takdirde ve her birinde ayrı ayrı karakter kümesi belirtmek çok külfetli olacaksa kullanılmalıdır. Buna bir örnek, CGI betikleri tarafından üretilmiş içeriğe sahip kaynaklara karakter kümesinin eklenmesidir; böyle kaynaklar çıktıda kullanıcı tarafından sağlanmış veri içermeleri nedeniyle karşı siteden kaynaklanan betikli saldırılardan zarar görebilir. Bununla birlikte, bir öntanımlı karakter kümesi belirtmek, tarayıcılarında “karakter kodlamasını kendiliğinden sapta” özelliğini etkin kılmış kullanıcıları korumayacağından daha iyi bir çözüm bu betikleri bu tür saldırılara karşı düzeltmek veya en iyisi silmektir.

Ayrıca bakınız:

  • AddCharset

AllowEncodedSlashes Yönergesi

Açıklama: | Kodlanmış dosya yolu ayracı içeren URL’lere izin verilip verilmeyeceğini belirler.
Sözdizimi: | AllowEncodedSlashes On|Off|NoDecode
Öntanımlı: | AllowEncodedSlashes Off
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core
Uyumluluk: | NoDecode seçeneği Apache httpd 2.3.12 ve sonrasında mevcuttur.

AllowEncodedSlashes yönergesi kodlanmış dosya yolu ayracı içeren URL’lere izin verir (/ yerine %2F ve ek olarak \ için ilgili sistemlerde %5C kullanılmış URL’ler).

Off öntanımlı değeriyle, böyle URL’ler bir 404 (Nesne bulunamadı) hatasıyla reddedilirler.

On değeriyle, böyle URL’ler kabul edilir ve kodlanmış dosya yolu ayraçları kodlanmış diğer karakterler gibi çözümlenir.

NoDecode değeriyle, böyle URL’ler kabul edilir fakat kodlanmış dosya yolu ayraçları çözümlenmeden kodlanmış halde bırakılır.

AllowEncodedSlashes On, çoğunlukla PATH_INFO ile bir arada kullanıldığı zaman kullanışlıdır.

Ek Bilgi

Kodlanmış bölü çizgileri yol bilgisi için gerekliyse bir güvenlik ölçütü olarak NoDecode kullanımı şiddetle önerilir. Kodlanmış bölü çizgilerinin çözümlenmesine izin vermek güvensiz olması olası yollara izin vermek olurdu.

Ayrıca bakınız:

  • AcceptPathInfo

AllowOverride Yönergesi

Açıklama: | .htaccess dosyalarında bulunmasına izin verilen yönerge türleri belirtilir.
Sözdizimi: | AllowOverride All|None|yönerge-türü [yönerge-türü] ...
Öntanımlı: | AllowOverride None (2.3.9 ve sonrası), AllowOverride All (2.3.8 ve öncesi)
Bağlam: | dizin
Durum: | Çekirdek
Modül: | core

Sunucu AccessFileName yönergesi ile belirtildiği şekilde bir .htaccess dosyasına rastlarsa önceki yapılandırma yönergelerinin hangilerinin geçersiz kılınmak üzere bildirildiğini bilmek ister.

Sadece <Directory> bölümlerinde geçerli

AllowOverride yönergesi, <Location>, <DirectoryMatch> veya <Files> bölümlerinde değil, sadece düzenli ifade içermeyen <Directory> bölümlerinde geçerlidir.

Bu yönergeye ve AllowOverrideList yönergesine değer olarak None belirtilirse .htaccess dosyaları tamamen yok sayılır. Bu durumda, sunucu dosya sisteminde rastladığı .htaccess dosyalarını okumaya dahi çalışmayacaktır.

Bu yönergeye All değeri atanırsa, .htaccess bağlamında kullanılabilecek her yönergeye .htaccess dosyalarında izin verilir.

yönerge-türü olarak aşağıdaki yönerge grup isimlerinden biri belirtilebilir:

AuthConfig
AuthDBMGroupFile, AuthDBMUserFile, AuthGroupFile, AuthName, AuthType, AuthUserFile, Require ve benzeri yetkilendirme yönergelerinin kullanımını izin verilir.
FileInfo
Belge türünü denetleyen mod_mime Add* ve Remove* yönergeleri, ErrorDocument, ForceType, LanguagePriority, SetHandler, SetInputFilter, SetOutputFilter yönergeleri ve benzerleri ile Header, RequestHeader, SetEnvIf, SetEnvIfNoCase, BrowserMatch, CookieExpires, CookieDomain, CookieStyle, CookieTracking, CookieName belge meta veri yönergelerinin, mod_rewrite modülündeki RewriteEngine, RewriteOptions, RewriteBase, RewriteCond, RewriteRule yönergelerinin, mod_alias modülündeki Redirect, RedirectTemp, RedirectPermanent, RedirectMatch) yönergelerinin ve mod_actions modülündeki Action yönergesinin kullanımına izin verilir.
Indexes
Dizin içeriğinin listelenmesini denetleyen AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName yönergelerinin ve benzerlerinin kullanımına izin verilir.
Limit
Konak erişimini denetleyen Allow, Deny ve Order yönergelerinin kullanımına izin verilir.
Nonfatal=[Override|Unknown|All]
.htaccess dosyalarındaki sözdizimi hatalarının ölümcül olarak ele alınmaması için AllowOverride yönergesinin kullanımına izin verir; bunun yerine bir dahili sunucu hatasına sebep olur, izin verilmeyen veya tanınmayan yönergeler yoksayılır ve günlüğe bir uyarı çıktılanır:
  • Nonfatal=Override ile AllowOverride tarafından yasaklanmış yönergeler ölümcül olarak ele alınmaz.
  • Nonfatal=Unknown ile bilinmeyen yönergeler ölümcül olarak ele alınmaz. Yazım hatalarını ve mevcut olmayan bir modül tarafından gerçeklenmiş yönergeleri kapsar.
  • Nonfatal=All ile yukarıdakilerin ikisi de ölümcül olarak ele alınmaz.

Geçerli bir yönergedeki yazım hatalarının hala dahili bir sunucu hatasına sebep olacağına dikkat ediniz.

Güvenlik

Ölümcül olmayan hatalar .htaccess kullanıcıları için güvenlikle ilgili sorunlara yol açabilir. Örneğin AllowOverride AuthConfig'e izin vermezse kullanıcıların siteye erişimini kısıtlayan yapılandırma iptal edilmiş olur.
Options[=seçenek,...]
Dizinlere özgü özellikleri denetleyen Options ve XBitHack yönergelerinin kullanımına izin verilir. Options komutunda belirtilecek seçenekler bir eşit işaretinden sonra aralarına sadece virgül konarak, fakat virgülden sonra boşluk bırakmadan belirtilebilir.

Options'ın örtük iptali

.htaccess dosyalarında kullanılabilen seçenek listesi bu yönergeyle sınırlanabilirse de herhangi bir Options yönergesine izin verildiği sürece miras alınmış diğer seçenekler göreli olmayan sözdizimi kullanılarak iptal edilebilir. Başka bir deyişle, bu mekanizma diğerlerinin değerlerini korumasına izin verirken belli bir seçeneği değerini korumaya zorlayamaz.

AllowOverride Options=Indexes,MultiViews

Örnek:

AllowOverride AuthConfig Indexes

Bu örnekte AuthConfig ve Indexes grubundaki yönergeler bir dahili sunucu hatasına yol açmayacaktır.

Güvenlik ve başarımı arttırmak için <Directory "/"> bloğu içinde AllowOverride yönergesine None dışında bir değer atamayın. Böyle yapmak yerine bir .htaccess dosyası yerleştirmeyi düşündüğünüz dizine ait bir <Directory> bloğu olması daha iyidir.

Ayrıca bakınız:

  • AccessFileName
  • AllowOverrideList
  • Yapılandırma Dosyaları
  • .htaccess Dosyaları

AllowOverrideList Yönergesi

Açıklama: | .htaccess dosyalarında izin verilecek yönergeler tek tek belirtilir
Sözdizimi: | AllowOverrideList None|yönerge [yönerge-türü] ...
Öntanımlı: | AllowOverrideList None
Bağlam: | dizin
Durum: | Çekirdek
Modül: | core

Sunucu bir .htaccess dosyası (AccessFileName tarafından belirtildiği gibi) bulduğunda önceki yapılandırma yönergelerini geçersiz kılabilen bu dosyada hangi yönergelerin bildirildiğini bilmek ister.

Sadece <Directory> bölümlerinde kullanılabilir

AllowOverrideList sadece <Directory> bölümlerinde düzenli ifadeler olmaksızın belirtilmişse kullanılabilir; <Location>, <DirectoryMatch> veya <Files> bölümlerinde değil.

Bu yönergeye ve AllowOverride yönergesine None atanmışsa .htaccess dosyaları tamamen yoksayılır. Bu durumda sunucu dosya sistemindeki .htaccess dosyalarını okumaya bile çalışmayacaktır.

Örnek:

AllowOverride None
AllowOverrideList Redirect RedirectMatch

Yukarıdaki örnekte sadece Redirect ve RedirectMatch yönergelerine izin verilmektedir. Tüm diğerleri dahili bir sunucu hatasına sebep olacaktır.

Örnek:

AllowOverride AuthConfig
AllowOverrideList CookieTracking CookieName

Yukarıdaki örnekte AllowOverride yönergesi AuthConfig yönerge grubuna izin verirken AllowOverrideList yönergesi FileInfo yönerge grubundan yalnız iki yönergeye izin vermektedir. Tüm diğerleri dahili bir sunucu hatasına sebep olacaktır.

Ayrıca bakınız:

  • AccessFileName
  • AllowOverride
  • Yapılandırma Dosyaları
  • .htaccess Dosyaları

CGIMapExtension Yönergesi

Açıklama: | CGI betik yorumlayıcısını saptama tekniğini belirler.
Sözdizimi: | CGIMapExtension cgi-yolu .uzantı
Bağlam: | dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Sadece NetWare’de geçerlidir.

Bu yönerge Apache httpd’nin CGI bekitlerini çalıştırmak için kullanacağı yorumlayıcıyı nasıl bulacağını denetlemek için kullanılır. Örneğin, CGIMapExtension sys:\foo.nlm .foo satırı .foo uzantılı CGI betik dosyalarının FOO yorumlayıcıya aktarılmasını sağlar.

CGIPassAuth Yönergesi

Açıklama: | HTTP yetkilendirme başlıklarının betiklere CGI değişkenleri olarak aktarılmasını etkin kılar
Sözdizimi: | CGIPassAuth On|Off
Öntanımlı: | CGIPassAuth Off
Bağlam: | dizin, .htaccess
Geçersizleştirme: | AuthConfig
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache HTTP Sunucusunun 2.4.13 ve sonraki sürümlerinde kullanılabilmektedir

CGIPassAuth yönergesi, HTTP Temel kimlik doğrulamasını gerçekleştiren betikler için gereken Authorization gibi HTTP yetkilendirme başlıklarına betiklerin erişebilmesini sağlar. Normalde bu HTTP başlıkları betiklerden gizli olup sunucuda HTTP Temel kimlik kanıtlaması etkin kılındığında sunucuya erişmekte kullanılan kullanıcı kimliklerinin ve parolalarının betikler tarafından görülmemesini mümkün kılar. Bu yönerge, HTTP Temel kimlik kanıtlamasını betiklerin gerçekleştirmesini sağlamak için kullanılmalıdır.

Apache HTTP Sunucusunun önceki sürümlerinde derleme sırasında kullanılabilen SECURITY_HOLE_PASS_AUTHORIZATION sabitinin yerine bu yönerge kullanılabilir.

Bu ayarlama mod_cgi, mod_cgid, mod_proxy_fcgi, mod_proxy_scgi ve benzerleri gibi ap_add_common_vars() kullanan modüller tarafından kabul görür. Özellikle, isteği alışılmış tarzda işleme sokmayıp bu arayüzü kullanan modülleri etkiler. Ayrıca, ap_add_common_vars() kullanmayan üçüncü parti modüller de bu ayarlamayı kullanmayı tercih edebilir.

ContentDigest Yönergesi

Açıklama: | Content-MD5 HTTP yanıt başlıklarının üretimini etkin kılar.
Sözdizimi: | ContentDigest On|Off
Öntanımlı: | ContentDigest Off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Options
Durum: | Çekirdek
Modül: | core

Bu yönerge RFC2616 ve RFC1864’te tanımlandığı gibi Content-MD5 üretimini etkin kılar.

MD5, verideki herhangi bir değişikliğin ileti özetinin değişmesi olarak yansıması nedeniyle yüksek derecede itimat sağlayan keyfi uzunlukta bir "ileti özeti" (bazen "parmakizi" dendiği de olur) hesaplama algoritmasıdır.

Content-MD5 başlığı öğe gövdesinin iki uç arasında ileti bütünlük sınamasının yapılabilmesini sağlar. Bir istemci veya vekil aktarılan öğe gövdesinde rastlantısal bir değişiklik olup olmadığını saptamak için bu başlığın doğruluğunu sınayabilir. Başlık örneği:

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

Her istekte ileti özeti hesaplanacağından (değerler saklanmaz), bu yönergenin sunucunuzda başarım sorunlarına yol açacağına dikkat ediniz.

Content-MD5, herhangi bir modül değil, sadece core modülü tarafından sunulan belgeler için gönderilir. Örneğin, SSI belgeleri CGI betikleri tarafından çıktılanırlar ve bayt seviyesinden çıktılar bu başlığa sahip olmazlar.

DefaultRuntimeDir Yönergesi

Açıklama: | Sunucunun çalışma anı dosyaları için temel dizin
Sözdizimi: | DefaultRuntimeDir dizin-yolu
Öntanımlı: | DefaultRuntimeDir DEFAULT_REL_RUNTIMEDIR (logs/)
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache 2.4.2 ve sonrasında kullanılabilmektedir.

DefaultRuntimeDir yönergesi sunucunun çalışma anında oluşturacağı dosyaların (paylaşımlı bellek, kilitler, vb.) saklanacağı dizini belirtmekte kullanılır. Göreli bir yol belirtilirse tam yol ServerRoot yönergesinde belirtilene göreli olacaktır.

Örnek

DefaultRuntimeDir scratch/

DefaultRuntimeDir için öntanımlı yer derleme sırasında DEFAULT_REL_RUNTIMEDIR #define satırı ile değiştirilebilir.

Bilgi: ServerRoot bu yönergeden önce belirtilmiş olmalıdır, aksi takdirde temel dizin için öntanımlı ServerRoot kullanılır.

Ayrıca bakınız:

  • ServerRoot üzerindeki izinlerin düzgün olarak nasıl ayarlanacağını öğrenmek için: güvenlik ipuçları

DefaultType Yönergesi

Açıklama: | Değeri none olduğu takdirde, bu yönergenin bir uyarı vermekten başka bir etkisi yoktur. Önceki sürümlerde, bu yönerge, sunucunun ortam türünü saptayamadığı durumda göndereceği öntanımlı ortam türünü belirlerdi.
Sözdizimi: | DefaultType ortam-türü|none
Öntanımlı: | DefaultType none
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | none değeri Apache httpd 2.2.7 ve sonrasında mevcuttur. Diğer tüm seçenekler Apache httpd'nin 2.3.x ve sonraki sürümleri için iptal edilmiştir.

Bu yönerge iptal edilmiştir. Yapılandırma dosyalarının geriye uyumluluğunu sağlamak için, öntanımlı bir ortam türünün olmadığını belirten none değeriyle belirtilebilir. Örnek:

DefaultType None

DefaultType None sadece httpd-2.2.7 ve sonrasında mevcuttur.

Ortam türlerini dosya uzantıları üzerinden yapılandırmak için AddType yönergesini ve mime.types yapılandırma dosyasını veya belli özkaynak türleri için ortam türlerini yapılandırmak için ForceType yönergesini kullanın.

Define Yönergesi

Açıklama: | Bir değişken tanımlar
Sözdizimi: | Define değişken-ismi [değişken-değeri]
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core

Tek değiştirgeli biçemi httpd’yi -D seçeneğiyle çalıştırmaya eşdeğerdir. Bu yönerge, başlatma betiğinde -D seçeneğinin argümanlarını değiştirme gereği duymaksızın <IfDefine> bölümlerini kullanıma sokmak için kullanılabilir.

Buna ek olarak, ikinci değiştirge belirtilirse yapılandırma değişkenine bu değer atanır. Değişken yapılandırmada ${VAR} sözdizimi ile kullanılabilir. Değişken daima küresel olarak tanımlı olup yapılandırma bölümünü sarmalayan etki alanı ile sınırlanmaz.

<IfDefine TEST>
  Define servername test.example.com
</IfDefine>
<IfDefine !TEST>
  Define servername www.example.com
  Define SSL
</IfDefine>
DocumentRoot "/var/www/${servername}/htdocs"

RewriteMap sözdizimi ile karışmalardan kaçınmak için değişken isimleri ikinokta ":" karakterleri içeremez.

<Directory> Yönergesi

Açıklama: | Sadece ismi belirtilen dosya sistemi dizininde ve bunun altdizinlerinde ve bunların içeriğinde uygulanacak bir yönerge grubunu sarmalar.
Sözdizimi: | <Directory "dizin-yolu"> ... </Directory>
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

<Directory> ve </Directory> sadece ismi belirtilen dosya sistemi dizininde, bunun altdizinlerinde ve bu dizinlerin içindeki dosyalara uygulanacak bir yönerge grubunu sarmalamakta kullanılır. Bir dizin bağlamında kullanılabilecek her yönergeye izin verilir. dizin-yolu bir dizinin tam yolu olabileceği gibi Unix kabuk tarzı bir dosya ismi eşleştirme kalıbı da olabilir. Kalıp dizgesinde, ? herhangi bir tek karakterle, * herhangi bir karakter dizisiyle eşleşir. Ayrıca [] karakter aralıkları da kullanılabilir. ‘/’ karakteri ile hiçbir kalıp karakteri eşleşmez, bu bakımdan <Directory "/*/public_html"> ile /home/user/public_html değil, ama <Directory "/home/*/public_html"> eşleşecektir. Örnek:

<Directory "/usr/local/httpd/htdocs">
  Options Indexes FollowSymLinks
</Directory>

Dizin yollarında isterseniz önceleme kullanabilirsiniz, ancak eğer yol bazı boşluklar içeriyorsa mutlaka kullanmanız gerekir. Bir boşluk aksi belirtilmedikçe bir ifadenin sonunu belirlediğinden bu gereklidir.

dizin-yolu argümanlarını belirtirken dikkatli olmalısınız: Apache httpd’nin dosyalara erişmekte kullandığı dosya sistemi yolu ile bire bir eşleşmelidir. Belli bir <Directory> dizinine uygulanan yönergeler, aynı dizine farklı bir yoldan, örneğin başka bir sembolik bağ üzerinden erişilen dosyalara uygulanmayacaktır.

~ karakterine ek olarak düzenli ifadeler de kullanılabilir. Örnek:

<Directory ~ "^/www/[0-9]{3}">

</Directory>

yönergesi /www/ içindeki üç rakamdan oluşan dizinlerle eşleşecektir.

Eğer çok sayıda (düzenli ifade olmayan) <Directory> bölümü, bir dosyayı içeren bir dizinle veya üst dizinlerinden biri ile eşleşiyorsa, uygulama en kısa eşleşmedeki yönergelerden başlayarak .htaccess dosyalarındaki yönergelere kadar genişletilir. Örneğin,

<Directory "/">
  AllowOverride None
</Directory>

<Directory "/home">
  AllowOverride FileInfo
</Directory>

bölümleri ile /home/web/dir/doc.html belgesine erişirken şu aşamalardan geçilir:

  • AllowOverride None yönergesi uygulanır (.htaccess dosyaları iptal edilir).
  • AllowOverride FileInfo yönergesi uygulanır (/home dizini için).
  • Sırayla /home/.htaccess, /home/web/.htaccess ve /home/web/dir/.htaccess dosyaları içindeki FileInfo yönergeleri uygulanır.

Normal bölümlerin tamamı uygulanıncaya kadar düzenli ifadeler değerlendirilmez. Düzenli ifadelerin tamamı yapılandırma dosyasında görüldükleri sıraya göre sınanırlar. Örneğin,

<Directory ~ "abc$">
  # ... yönergeler burada ...
</Directory>

düzenli ifadeli bölümü, tüm normal <Directory> bölümleri ve .htaccess dosyaları uygulanıncaya kadar değerlendirilmeyecektir. Düzenli ifadeleri değerlendirmeye sıra gelince düzenli ifade /home/abc/public_html/abc ile eşleştirilecek ve buna ilişkin <Directory> uygulanacaktır.

<Directory "/"> için öntanımlı erişimin tüm erişime izin vermek oluşuna dikkat ediniz. Bunu şöyle bir blokla değiştirmeniz,

<Directory "/">
  Require all denied
</Directory>

ve erişilebilir olmasını istediğiniz dizinleri ayrıca belirtmeniz önerilir. Daha ayrıntılı bilgi edinmek için Güvenlik İpuçları belgesine bakınız.

Dizin bölümleri httpd.conf dosyasında yer alır. <Directory> yönergeleri iç içe olamazlar ve bir <Limit> veya <LimitExcept> bölümü içinde bulunamazlar.

Ayrıca bakınız:

  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

<DirectoryMatch> Yönergesi

Açıklama: | Bir düzenli ifade ile eşleşen dosya sistemi dizinlerinin içeriklerine uygulanacak bir yönerge grubunu sarmalar.
Sözdizimi: | <DirectoryMatch düzifd> ... </DirectoryMatch>
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

<DirectoryMatch> and </DirectoryMatch> yönergeleri <Directory> gibi sadece ismi belirtilen dosya sistemi dizininde ve içindeki dosyalarda uygulanacak bir yönerge grubunu sarmalamakta kullanılır. Tek farkla argüman olarak bir düzenli ifade alır. Örnek:

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

yönergesi /www/ içindeki (veya alt dizinlerindeki) üç rakamdan oluşan dizinlerle eşleşecektir.

Uyumluluk

2.3.9 öncesinde, bu yönerge örtük olarak (<Directory> gibi) alt dizinlere de uygulanırdı ve satır sonu simgesi ($) ile eşleşemezdi. 2.3.9 ve sonrasında, sadece ifade ile eşleşen dizinler sarmalanan yönerge grubundan etkilenmektedir.

Sondaki bölü çizgileri

Bu yönerge bir bölü çizgisi ile sonlanan veya sonlanmayan dizinler için yapılan isteklere uygulanır, dolayısıyla satır sonuna ($) çıpalanmış ifadeler dikkatli yazılmalıdır.

2.4.8 itibariyle, isimli gruplar ve geriye başvurular elde edilmekte olup ilgili isim büyük harfe çevrildikren sonra "MATCH_" ile öncelendikten sonra ortama yazılmaktadır. Böylece yol elemanlarına mod_rewrite gibi modüllerden veya düzenli ifadelerden başvurmak mümkün kılınmıştır. Karışıklığı önlemek için, numaralı (isimsiz) geriye başvurular yoksayılmaktadır. Bunların yerine isimli geriye başvurular kullanılmalıdır.

<DirectoryMatch "^/var/www/combined/(?<sitename>[^/]+)">
    require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</DirectoryMatch>

Ayrıca bakınız:

  • Normal <Directory> bölümlerindeki yönergelerle düzenli ifadelerin nasıl karıştırıldığının bir açıklaması için <Directory> yönergesine bakınız.
  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

DocumentRoot Yönergesi

Açıklama: | İstemciye görünür olan ana belge ağacının kök dizinini belirler.
Sözdizimi: | DocumentRoot dizin-yolu
Öntanımlı: | DocumentRoot "/usr/local/apache/htdocs"
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Bu yönerge httpd tarafından dosyalarının sunulacağı dizini belirler. Alias benzeri bir yönerge ile eşleşmedikçe, sunucu istenen URL’deki yolu, belge yolu haline getirmek için belge kök dizinine ekler. Örnek:

DocumentRoot "/usr/web"

yapılandırması ile http://my.example.com/index.html isteği /usr/web/index.html ile eşleştirilir. dizin-yolu ile göreli dosya yolu belirtildiği takdirde belge kök dizininin ServerRoot ile belirtilen sunucu kök dizinine göre belirtildiği varsayılır.

DocumentRoot ile belirtilen dizin bir bölü çizgisi ile bitirilmemelidir.

Ayrıca bakınız:

  • URL’lerin Dosya Sistemi ile Eşlenmesi

<Else> Yönergesi

Açıklama: | Önceki bir <If> veya <ElseIf> bölümünün koşulu, çalışma anında bir istek tarafından yerine getirilmediği takdirde uygulanacak yönergeleri içerir
Sözdizimi: | <Else> ... </Else>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<Else> sadece ve sadece aynı etki alanındaki en son <If> veya <ElseIf> bölümü uygulanmamışsa kapsadığı yönergeleri uygular. Örneğin:

<If "-z req('Host')">
  # ...
</If>
<Else>
  # ...
</Else>

Burada, <If> yönergesi Host: başlıksız HTTP/1.0 istekleriyle eşleşirken <Else> Host: başlıklılarla eşleşir.

Ayrıca bakınız:

  • <If>
  • <ElseIf>
  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız. <If>, <ElseIf> ve <Else> son olarak uygulanır.

<ElseIf> Yönergesi

Açıklama: | İçerdiği koşulun bir istek tarafınan sağlandığı ancak daha önceki bir <If> veya <ElseIf> bölümlerininkilerin sağlanmadığı durumda kapsadığı yönergelerin uygulanmasını sağlar
Sözdizimi: | <ElseIf ifade> ... </ElseIf>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<ElseIf> kapsadığı yönergeleri sadece ve sadece belirtilen koşulun doğrulandığı ancak aynı etki alanında hemen önceki <If> veya <ElseIf> yönergesinin uygulanmadığı takdirde uygular. Örnek:

<If "-R '10.1.0.0/16'">
  #...
</If>
<ElseIf "-R '10.0.0.0/8'">
  #...
</ElseIf>
<Else>
  #...
</Else>

<ElseIf> bir isteğin uzak adresi 10.0.0.0/8 ağına aitse ama 10.1.0.0/16 ağına ait değilse içerdiği yönergelerin uygulanmasını sağlar.

Ayrıca bakınız:

  • Tam bir kaynak ve daha fazla örnek için: Apache HTTP Sunucusundaki ifadeler
  • <If>
  • <Else>
  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız. <If>, <ElseIf> ve <Else> son olarak uygulanır.

EnableMMAP Yönergesi

Açıklama: | Teslimat sırasında okunacak dosyalar için bellek eşlemeyi etkin kılar.
Sözdizimi: | EnableMMAP On|Off
Öntanımlı: | EnableMMAP On
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | none değeri Apache 2.2.7 ve sonrasında mevcuttur.

Bu yönerge, sunucunun teslimat sırasında gerektiği takdirde bir dosya içeriğinin okunması için bellek eşleme kullanıp kullanmayacağını belirler. Öntanımlı olarak, bir isteğin yerine getirilmesi, mod_include kullanarak sunucu tarafından çözümlenen bir dosyanın teslimatı sırasında olduğu gibi, bir dosya içindeki veriye erişilmesini gerektirdiğinde Apache httpd, işletim sistemi tarafından desteklendiği takdirde dosyayı belleğe eşler.

Böyle bellek eşleme kimi zaman başarım artışını beraberinde getirirse de bazen sorunlardan kaçınmak için bellek eşlemeyi kapatmak daha iyi sonuç verir:

  • Bazı çok işlemcili sistemlerde bellek eşleme httpd’nin başarımını düşürebilmektedir.
  • httpd bellek eşlemli çalışırken bir dosyanın silinmesi veya boyutunun küçültülmesi httpd'nin parçalama arızası vererek çökmesine yol açabilir.

Bu tür sorunlardan dolayı zarar görülebilecek sunucu yapılandırmalarında dosya teslimatında bellek eşlemlerinin kullanımını şu şekilde iptal etmeniz gerekir:

EnableMMAP Off

Bu özellik, sadece NFS dosya sistemi üzerinde sunulan dosyaları kapsamak üzere şu şekilde kolayca kapatılabilir:

<Directory "/nfs-dosyaları-yolu">
  EnableMMAP Off
</Directory>

EnableSendfile Yönergesi

Açıklama: | Dosyaların istemciye tesliminde çekirdeğin dosya gönderme desteğinin kullanımını etkin kılar.
Sözdizimi: | EnableSendfile On|Off
Öntanımlı: | EnableSendfile Off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Öntanımlı değer 2.3.9 sürümünde Off olarak değişti.

Bu yönerge, dosya içeriğinin istemciye teslimi için httpd’nin çekirdeğin dosya gönderme desteğini kullanıp kullanmayacağını belirler. Öntanımlı olarak, bir isteğin yerine getirilmesi, bir durağan dosyanın teslimatı sırasında olduğu gibi, bir dosya içindeki veriye erişilmesini gerektirmediği takdirde Apache httpd, işletim sistemi tarafından destekleniyorsa dosyayı istemciye teslim etmek için çekirdeğin dosya gönderme özelliğini kullanır.

Çekirdeğin dosya gönderme mekanizması, okuma, gönderme ve tampon ayırma işlemlerini ayrı ayrı yapmaktan kaçınır. Fakat bazı platformlarda veya bazı dosya sistemlerinde aşağıda belirtilen işlemsel sorunlardan kaçınmak için bu özelliği iptal etmek daha iyidir:

  • Bazı platformlar, derleme sistemince saptanamayan bozuk bir dosya gönderme desteğine sahiptir; özellikle eğer derleme işlemi dosya gönderme desteğinde sorun olmayan bir makinede yapılıp çalıştırılabilir dosyaların sorunlu makineye kurulduğu durumda bu saptama yapılamayacaktır.
  • Linux’ta IPv6 kullanırken dosya gönderme desteği bazı ağ kartlarındaki TCP toplama sağlaması aktarım hatasını tetikler.
  • Itanium üzerinde çalışan Linux’ta dosya gönderme desteği (sendfile) 2GB’tan büyük dosyalarla çalışamamaktadır.
  • DocumentRoot ağ dosya sistemi (NFS, SMB, CIFS, FUSE gibi) üzerinde olduğu durumda çekirdek ağ dosyalarını kendi arabelleği üzerinden sunamayabilir.

Bu sorunlardan muzdarip sunucu yapılandırmaları için bu özelliği şöyle etkin kılabilirsiniz:

EnableSendfile On

Bu özellik, sadece bir ağ dosya sistemi üzerinde sunulan dosyaları kapsamak üzere şu şekilde kolayca kapatılabilir:

<Directory "/nfs-dosyaları-yolu">
  EnableSendfile Off
</Directory>

EnableSendfile yönergesinin .htaccess ve diziniçi yapılandırmalarının mod_cache_disk tarafından desteklenmediğini lütfen aklınızdan çıkarmayın. EnableSendfile yönergesinin sadece küresel tanımları hesaba katılır.

Error Yönergesi

Açıklama: | Özel bir hata iletisiyle yapılandırma çözümlemesini durdurur
Sözdizimi: | Error ileti
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Durum: | Çekirdek
Modül: | core
Uyumluluk: | 2.3.9 ve sonrası

Yapılandırmada bir hatanın saptanması istenirse, bu yönerge yapılandırma çözümlemesinin durdurulması ve özel bir hata iletisi üretilmesi için kullanılabilir. Genelde kullanıldığı durum, gerekli modüllerin yapılandırmada bulunmadığının raporlanmasıdır.

# Örnek
# mod_include yüklü değilse bilelim
<IfModule !include_module>
  Error "Hata: mod_include mod_foo için gerekiyor. LoadModule ile yükleyin."
</IfModule>

# SSL veya NOSSL tanımlı mı bilelim
<IfDefine SSL>
<IfDefine NOSSL>
  Error "Ne SSL ne de NOSSL tanımlı. Sadece biri tanımlı olsa yeter."
</IfDefine>
</IfDefine>
<IfDefine !SSL>
<IfDefine !NOSSL>
  Error "Ya SSL ya da NOSSL tanımlı olmalı."
</IfDefine>
</IfDefine>

ErrorDocument Yönergesi

Açıklama: | Bir hata durumunda sunucunun istemciye ne döndüreceğini belirler.
Sözdizimi: | ErrorDocument hata-kodu belge
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core

Bir sorun çıktığında veya hata oluştuğunda Apache httpd şu dört işlemden birini yapacak şekilde yapılandırılabilir:

  1. Yerleşik bir hata iletisi çıktılanır.
  2. Özel bir ileti çıktılanır.
  3. Sorunu/hatayı işleyecek yerel bir URL-yoluna dahili bir yönlendirme yapılır.
  4. Sorunu/hatayı işleyecek harici bir URL-yoluna yönlendirme yapılır.

İlk seçenek öntanımlıdır. Diğer üç seçenek ErrorDocument yönergesinin argümanları (hata kodundan sonra bir URL veya hata iletisi) ile belirtilir. Apache httpd bazı durumlarda sorun/hata ile ilgili ek bilgi verecektir.

2.4.13 itibariyle, özdevinimli dizgeler ve URLler üretmek için yönerge içinde ifade sözdizimi kullanılabilir.

URL’ler yerel yollarda (DocumentRoot’a göre) bir bölü çizgisi (/) ile başlatılabileceği gibi istemci tarafından çözümlenecek tam bir URL şeklinde de belirtilebilir. Bunlar yerine, tarayıcıda gösterilmek üzere bir ileti de belirtilebilir. Örnekler:

ErrorDocument 500 http://foo.example.com/cgi-bin/tester
ErrorDocument 404 /cgi-bin/bad_urls.pl
ErrorDocument 401 /subscription_info.html
ErrorDocument 403 "Kusura bakmayın, bugün hizmet veremiyoruz."
ErrorDocument 403 /cgi-bin/forbidden.pl?referrer=%{escape:%{HTTP_REFERER}}

Bunlardan başka, Apache httpd’nin kendi hata iletilerinin kullanılacağı özel default değeri ile belirtilebilir. Normal şartlar altında gerekmese de, bir şey belirtilmediği takdirde mevcut bir ErrorDocument yönergesini miras alan yapılandırmalarda Apache httpd’nin kendi hata iletilerinin kullanımı default değeri açıkça belirtilerek örnekteki gibi zorlanabilir:

ErrorDocument 404 /cgi-bin/bad_urls.pl

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

ErrorDocument yönergesinde bir uzak URL (önünde http bulunan bir yol) belirtildiğinde, belge aynı sunucuda olsa bile, Apache HTTP Sunucusunun istemciye belgeyi bulacağı yer için bir yönlendirme göndereceğine dikkat ediniz. Bunun bazı istenmeyen etkileri vardır; en önemlilerinden biri istemcinin hata kodu yerine bir yönlendirme durum kodu alacak olmasıdır. Bu, bir URL’nin geçerliliğini durum koduna göre saptayan istemciler veya robotlar için yanıltıcı olacaktır. Buna ek olarak, ErrorDocument 401 için bir uzak URL belirttiğiniz durumda istemci 401 durum kodunu almayacağı için kullanıcıdan parola isteğinde bulunamayacaktır. Bu bakımdan, ihtiyaç duyduğunuz takdirde, ErrorDocument 401 yönergesine yerel bir belge belirtmelisiniz.

Sunucunun ürettiği hata iletileri "çok kısa" olduğu takdirde, Microsoft Internet Explorer (MSIE) öntanımlı olarak bu hata iletilerini yoksayar ve bunun yerine kendi "kullanıcı dostu" hata iletilerini kullanır. "Çok kısa" eşiği duruma göre değişmekle birlikte, genellikle, hata iletileriniz 512 bayttan büyük olduğu takdirde MSIE kendi hata iletileri yerine sunucunun ürettiği hata iletilerini gösterecektir. Bu konuda daha fazla bilgiyi Q294807 kodlu Microsoft Knowledge Base makalesinde bulabilirsiniz.

Çoğu yerleşik hata iletisi özel iletilerle değiştirilebilse de bazı durumlarda ErrorDocument ile ne belirtildiğine bakılmaksızın yerleşik hata iletileri kullanılır. Özellikle, bozuk bir istek saptandığında normal istek işleme hemen devre dışı bırakılır ve yerleşik hata iletisi döndürülür. Bu, hatalı istekler yaparak güvenlik sorunlarına yol açılmak istenmesi durumlarında gereklidir.

mod_proxy kullanıyorsanız, ProxyErrorOverride yönergesini etkin kılmak isteyebilirsiniz, böylece asıl sunucular adına özel hata iletileri üretebilirsiniz. ProxyErrorOverride etkin kılınmak istenmezse, Apache httpd vekalet edilen içerik için özel hata belgeleri üretmeyecektir.

Ayrıca bakınız:

  • Özel Hata Yanıtları

ErrorLog Yönergesi

Açıklama: | Sunucunun hata günlüğünü tutacağı yeri belirler.
Sözdizimi: | ErrorLog dosya-yolu|syslog[:oluşum]
Öntanımlı: | ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows ve OS/2)
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

ErrorLog yönergesi sunucunun saptadığı hataları kaydedeceği dosyanın ismini belirtmek için kullanılır. dosya-yolu ile göreli dosya yolu belirtildiği takdirde dizininin ServerRoot ile belirtilen sunucu kök dizinine göre belirtildiği varsayılır.

ErrorLog "/var/log/httpd/error_log"

dosya-yolu bir boru imi "|" ile başlatıldığı takdirde hata iletilerinin hata günlüğünü işleme sokacak komuta borulanacağı varsayılır.

ErrorLog "|/usr/local/bin/httpd_errors"

Daha fazla bilgi için borulu günlüklere bakınız.

Dosya adı yerine syslog kullanılırsa, sistem desteklediği takdirde günlük kaydı syslogd(8) üzerinden yürütülür. Öntanımlı olarak local7 syslog oluşumu kullanılır. Bunu syslog:oluşum sözdizimini kullanarak değiştirebilirsiniz. Buradaki oluşum syslog.conf(5) kılavuz sayfasında belirtilen oluşum isimlerinden biri olabilir. Oluşum aslında küreseldir ve sanal konaklardan bazılarında değiştirilmişse, belirtilen en son oluşum tüm sunucuyu etkileyecektir.

ErrorLog syslog:user

Buna ek olarak, modüller kendi günlük kaydı oluşturucusunu sağlayabilir. Sözdizimi yukarıdaki örnekte kullanılan syslog sözdiziminin benzeridir.

GÜVENLİK: Günlük dosyalarının saklandığı dizin, sunucuyu başlatan kullanıcı dışındakiler tarafından yazılabilir olduğu takdirde güvenliğinizin nasıl tehlikeye gireceği güvenlik ipuçları belgesinde ayrıntılı olarak açıklanmıştır.

Ek Bilgi

Unix-dışı platformlarda dosya yolunu girerken, platform ters bölü çizgilerini desteklese bile normal bölü çizgileri kullanmaya özen göstermelisiniz. Genel olarak, dosya yollarını belirtirken yapılandırma dosyası boyunca normal bölü çizgisi kullanmak her zaman daha iyidir.

Ayrıca bakınız:

  • LogLevel
  • Apache HTTP Sunucusunun Günlük Dosyaları

ErrorLogFormat Yönergesi

Açıklama: | Hata günlüğü girdileri için biçem belirtimi
Sözdizimi: | ErrorLogFormat [connection|request] biçem
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

ErrorLogFormat yönergesi, hata günlüğünde asıl hata iletisine ek olarak günlüklenecek ek bilgiyi belirtmek için kullanılabilir.

#Basit örnek
ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"

İlk değiştirge olarak connection veya request belirtilmesi ek biçemlerin belirtilebilmesini sağlar. Böylece, belli bir bağlantı ya da istek için ilk ileti günlüklendiğinde ek bilgininde günlüklenmesi sağlanır. Bu ek bilgi sadece bağlantı/istek başına bir kere günlüklenir. herhangi bir günlük iletisine sebep olmadan işlenmişse ek bilgi de günlüklenmez.

Bu, bazı biçem dizgesi öğeleri çıktı üretmediğinde olur. Örneğin, Referer başlığı sadece günlük iletisi bir istekle ilişkilendirilmişse mevcuttur ve hata iletisi Referer başlığı istemcide okunduğu anda oluşur. Eğer bir çıktı üretilmezse, öntanımlı davranış önceki boşluk karakterinden sonraki boşluk karakterine kadar herşeyi silmektir. Yani, günlük satırı örtük olarak boşluklarla ayrılmış alanlara bölünür. Bir biçem dizgesi öğesi çıktı üretmezse alanın tamamı çıktılanmaz. Örneğin, [%t] [%l] [%a] %M  günlük biçeminde uzak adres %a kullanılamazsa sarmalayıcı köşeli ayraçlar da günlüklenmeyecektir. Boşluk karakterleri ters bölülerle öncelenerek bir alanı sınırlaması önlenebilir. '% ' (yüzde boşluk) çifti sıfır genişlikte bir alan ayracı olup herhangi bir çıktı üretmez.

Yukarıdaki davranış, biçem dizgesi öğesine değiştirciler eklenerek değiştirilebilir. - (tire) değiştircisi ilgili öğe bir çıktı üretmediğinde tire iminin günlüklenmesine sebep olur. Bağlantı/istek başına bir kere biçemlerinde + (artı) değiştircisini de kullanmak mümkündür.Artı değiştiricili bir öğe herhangi bir çıktı üretmezse satırın tamamı günlüklenmez.

Bir biçem öğesine günlük önem derecesi atamak için değiştirici olarak bir sayı kullanılabilir. Bu öğenin günlüklenebilmesi için günlük iletisinin önem derecesinin belirtilen günlük önem derecesinden daha yüksek olmaması gerekir. Sayı 1'den (alarm) 4'e (uyarı) ve 7'den (hata ayıklama) 15'e (trace8) kadar olabilir.

Örneğin, Referer istek başlığını günlükleyen %{Referer}i dizgeciğine değiştirciler eklendiğinde neler olduğunu burada görebilirsiniz:

Değiştirlen Dizgecik | Anlamı
%-{Referer}i | Referer atanmamışsa bir - günüklenir.
%+{Referer}i | Referer atanmamışsa satırın tamamı çıktılanmaz.
%4{Referer}i | Sadece hata iletisinin önemi 4'ten yüksek olduğu durumda Referer günlüklenir.

Bazı biçem dizfesi öğeleri ayraç içine alınmış ek değiştirgeler kabul eder.

Biçem Dizgesi | Açıklama
%% | Yüzde imi
%a | İstekteki istemci IP adresi ve portu
%{c}a | Bağlantının emsal IP adresi and portu (mod_remoteip modülüne bakın)
%A | Yerel IP adresi ve portu
%{isim}e | İstek ortam değişkeni isim
%E | APR/OS hata durum kodu ve iletisi
%F | Günlük çağrısının kaynak dosya ismi ve satır numarası
%{isim}i | İstek başlığı isim
%k | Bağlantıdaki keep-alive isteklerinin sayısı
%l | İletinin günlük seviyesi
%L | İsteğin günlük kimliği
%{c}L | Bağlantının günlük kimliği
%{C}L | Bağlantı etki alanında kullanılmışsa bağlantının günlük kimliği, aksi takdirde boş
%m | İletiyi günlükleyen modülün ismi
%M | Asıl günlük iletisi
%{isim}n | istek notu isim
%P | Geçerli sürecin süreç kimliği (PID'i)
%T | Geçerli evrenin evre kimliği
%{g}T | Geçerli evrenin eşsiz sistem evre kimliği (örn, top tarafınan gösterilenle aynı kimlik: şimdilik sadece Linux'a özgü)
%t | geçerli zaman
%{u}t | Mikro saniyeler dahil geçerli zaman
%{cu}t | ISO 8601 biçemiyle uyumlu mikro saniyeleri de içeren geçerli zaman
%v | Geçerli sunucunun kurallı ServerName
%V | UseCanonicalName ayarına uygun olarak isteği sunan sunucunun sunucu ismi
\ (tersbölü boşluk) | Alan ayracı olmayan boşluk
% (yüzde boşluk) | Alan ayracı (çıktısız)

The log ID format %L günlük kimliği biçemi bağlantı veya istek için eşsiz bir kimlik üretir. Bu, bağlantı üzerinden gelen istek durumunda günlük satırlarının ait olduğu bağlantı veya isteği bağdaştırmak için kullanılabilir. %L biçem dizgesi ayrıca mod_log_config modülünde erişim günlüğü iletilerini hata günlüğü iletileriyle ilişklendirmek için de kullanılabilmektedir. mod_unique_id modülü yüklüyse onun eşsiz kimliği istekler için günlük kimliği olarak kullanılacaktır.

#Örnek (Evreli MPM'ler için öntanımlı biçim)
ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P:tid %T] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"

Bunun hata iletilerindeki sonuçları şöyle olabilir:

[Thu May 12 08:28:57.652118 2011] [core:error] [pid 8777:tid 4326490112] [client ::1:58619] File does not exist: /usr/local/apache2/htdocs/favicon.ico

Dikkat edin, yukarıda açıklandığı gibi, bazı alanlar tanımlanmadıklarından tamamen yoksayılır.

#Örnek (2.2.x biçimine benzer)
ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"
#İstek/bağlantı günlük kimlikli gelişkin bir örnek
ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M"
ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T"
ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'"
ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'"
ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"

Ayrıca bakınız:

  • ErrorLog
  • LogLevel
  • Apache HTTP Sunucusu Günlük Dosyaları

ExtendedStatus Yönergesi

Açıklama: | Her istekte ek durum bilgisinin izini sürer
Sözdizimi: | ExtendedStatus On|Off
Öntanımlı: | ExtendedStatus Off[*]
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

Bu yönerge, o an işlenmekte olan istek hakkında evre başına ek veriyi ve kullanım özetini izler; mod_status modülünü yapılandırarak bu değişkenleri çalışma anında görebilirsiniz. Diğer modüllerin bu sonuçlara bel bağlayabileceğini unutmayın.

Bu ayarlar sunucunun tamamına uygulanır ve bir sanal konakta etkin başka bir sanal konakta etkisiz kılınamaz. Ek durum bilgisinin toplanması sunucuyu yavaşlatabilir. Ayrıca, bu ayarın nazikçe yeniden başlatma sırasında değiştirilemeyeceğine dikkat ediniz.

Diğer üçüncü parti modüller aynısını yaparken mod_status modülünün yüklenmesi ExtendedStatus On için öntanımlı davranışı değiştirecektir. Böyle modüller, tüm evrelerin durumu hakkında ayrıntılı bilgi toplanmasına bel bağlar. Öntanımlı değer sürüm 2.3.6 itibariyle mod_status tarafından değiştirilmiştir. Önceki sürümlerde öntanımlı değer daima Off idi.

FileETag Yönergesi

Açıklama: | Duruk dosyalar için ETag HTTP yanıt başlığını oluşturmakta kullanılacak dosya özniteliklerini belirler.
Sözdizimi: | FileETag bileşen ...
Öntanımlı: | FileETag MTime Size
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | 2.3.14 ve öncesinde öntanımlı değer "INode MTime Size" idi.

FileETag yönergesi, belge bir duruk dosyaya dayandığı takdirde ETag (Entity Tag - öğe etiketi kısaltması) yanıt başlığı alanını oluşturmakta kullanılacak dosya özniteliklerini yapılandırır. (ETag değeri, ağ band genişliğinden kazanmak için arabellek yönetiminde kullanılır.) FileETagyönergesi ne kullanılması gerektiğini belirleyebilmenizi sağlar. Değer olarak belirtilebilecek anahtar sözcükler şunlardır:

INode
Dosyanın düğüm numarası hesaba katılır.
MTime
Dosyanın son değişiklik tarih ve saati dahil edilir.
Size
Dosyanın bayt cinsinden uzunluğu dahil edilir.
All
Olası tüm alanlar kullanılır. Bu şuna eşdeğerdir:
FileETag INode MTime Size
None
Bir belge dosyasıyla sunulsa bile yanıta hiçbir ETag alanı dahil edilmez.

Öntanımlı ayarları miras alıp bunların kapsamını genişletmek/daraltmak için INode, MTime ve Size anahtar sözcüklerinin önüne + veya - imi konabilir. Bu imlerin bulunmadığı bir anahtar sözcüğün varlığı halinde hiçbir değer miras alınmaz.

Eğer bir dizinin yapılandırması FileETag INode MTime Size ve alt dizini FileETag -INode içeriyorsa bu alt dizinin (ve bir geçersizleştirme olmadığı takdirde onun alt dizinlerinin) ayarları FileETag MTime Size yapılandırmasına eşdeğer olacaktır.

Uyarı

WebDAV’ın etkin olduğu yerlerde veya dizinlerde saklama alanı sağlayıcı olarak mod_dav_fs kullanılıyorsa öntanımlı ayarları değiştirmeyiniz. mod_dav_fs, koşullu isteklerde ETag karşılaştırmaları yapabilmek için MTime Size yapılandırmasını kullanır. Eğer ETag ayarı FileETag yönergesi kullanılarak değiştirilirse koşullu istekler gerektiği gibi yerine getirilemez.

Sunucu Taraflı İçerik

Gömülü SSI yönergeleri ile bir duruk dosyanın FileETag, MTime ve Size değerleri değişmeksizin yanıt öğesi değişebileceğinden mod_include tarafından çözümlenen yanıtlar için bir ETag üretilmez.

<Files> Yönergesi

Açıklama: | Dosya isimleriyle eşleşme halinde uygulanacak yönergeleri içerir.
Sözdizimi: | <Files "dosya-adı"> ... </Files>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<Files> yönergesi, içerdiği yönergelerin etki alanını dosya isimlerine göre sınırlandırır. <Directory> ve <Location> bölümleri ile karşılaştırılabilir. Bir </Files> yönergesi ile sonlandırılması gerekir. Bu bölüm içinde belirtilen yönergeler, <Files> yönergesinde belirtilen dosya-adı’nın son bileşeniyle (dizinler atıldıktan sonda kalan dosya ismi) eşleşen nesnelere uygulanır. <Files> bölümleri yapılandırma dosyasında, <Directory> bölümleri ve .htaccess dosyaları okunduktan sonra fakat <Location> yönergelerinden önce göründükleri sıraya göre işleme sokulurlar. <Files> bölümlerinin <Directory> bölümlerinin içinde uygulama alanını sınırlamak amacıyla kullanılabileceğine dikkat ediniz.

dosya-adı argümanının bir dosya ismi veya bir dosya ismi kalıbı içermesi gerekir. Bir dosya ismi kalıbındaki her ? imi bir karakterle eşleştirilirken * imi karakter dizileri ile eşleştirilir.

<Files "zat.html">
    # zat.html dosyasına uygulanacakları buraya koy
</Files>

<Files "?at.*">
    # Buradakiler hat.html, kat.html, tat.html ve benzerlerine uygulanır.
</Files>

~ imine ek olarak düzenli ifadeler de kullanılabilir. Örneğin

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

satırı en bilinen resim dosyası biçimleriyle eşleşecektir. Bunun yerine <FilesMatch> yönergesi de tercih edilebilirdi.

<Directory> ve <Location> bölümlerinin aksine, <Files> bölümleri .htaccess dosyaları içinde kullanılabilir. Bu sayede kullanıcıların kendi dosyalarına erişimi dosya seviyesinde denetlemelerine imkan sağlanmış olur.

Ayrıca bakınız:

  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

<FilesMatch> Yönergesi

Açıklama: | Düzenli ifadelerin dosya isimleriyle eşleşmesi halinde uygulanacak yönergeleri içerir.
Sözdizimi: | <FilesMatch düzifd> ... </FilesMatch>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<FilesMatch> yönergesi, içerdiği yönergelerin etki alanını <Files> yönergesinin yaptığı gibi dosya isimlerine göre sınırlandırır. Ancak, argüman olarak bir düzenli ifade kabul eder. Örneğin

<FilesMatch "\.(gif|jpe?g|png)$">
    # ...
</FilesMatch>

satırı en bilinen resim dosyası biçimleriyle eşleşecektir.

Düzenli ifadenin başlangıcındaki bir .+ .pngveya .gif dosyalarının, örnek olarak, eşleşmemesini garanti eder.

2.4.8 itibariyle, isimli gruplar ve geriye başvurular elde edilmekte olup ilgili isim büyük harfe çevrildikren sonra "MATCH_" ile öncelendikten sonra ortama yazılmaktadır. Böylece yol elemanlarına mod_rewrite gibi modüllerden veya düzenli ifadelerden başvurmak mümkün kılınmıştır. Karışıklığı önlemek için, numaralı (isimsiz) geriye başvurular yoksayılmaktadır. Bunların yerine isimli geriye başvurular kullanılmalıdır.

<FilesMatch "^(?<sitename>[^/]+)">
    require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</FilesMatch>

Ayrıca bakınız:

  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

ForceType Yönergesi

Açıklama: | Bütün dosyaların belirtilen ortam türüyle sunulmasına sebep olur.
Sözdizimi: | ForceType ortam-türü|None
Bağlam: | dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache httpd 2.0’da core modülüne taşındı.

Bu yönerge, bir .htaccess dosyası veya bir <Directory>, <Location> veya <Files> bölümüne yerleştirildiği zaman, eşleşen tüm dosyaların ortam-türü ile belirtilen içerik türüyle sunulmasına sebep olur. Örneğin, altında sadece GIF dosyaları bulunan bir dizininiz varsa ve bunlara tek tek .gif uzantısı belirtmek istemiyorsanız şu yapılandırmayı kullanabilirsiniz:

ForceType image/gif

Bu yönerge, AddType yönergesi üzerinden ve mime.types dosyasında örtük olarak tanımlanmış ortam türü/dosya uzantısı ilişkilerini geçersiz kılar.

Ayrıca, daha genel ForceType ayarlarını da None değeriyle geçersiz kılabilirsiniz:

# tüm dosyaların image/gif olarak sunulması için:
<Location "/images">
  ForceType image/gif
</Location>

# normal MIME-türüne geri dönmek için:
<Location "/images/mixed">
  ForceType None
</Location>

Bu yönerge, öncelikle dosya sisteminden sunulan duruk dosyalar için üretilen içerik türlerini geçersiz kılar. Duruk dosyaların haricindeki özkaynaklar için yanıt üretecinin genelde bir Content-Type belirttiği durumda bu yönerge etkisizdir.

Ek Bilgi

SetHandler veya AddHandler gibi örtük yönergeler geçerli isteğe uygulanmadığı takdirde, normalde bu yönergeler tarafından belirlenen dahili eylemcinin ismi ForceType yönergesi tarafından belirtilen içerik türü ile eşleşecek şekilde belirlenir. Bu, bazı üçüncü parti modüller (mod_php gibi) tarafından kullanılan tarihi bir uygulama olup, bu modüller istekle eşleşecek modüllerin sorumluluğu almasını sağlamak için "sihirli" içerik türleri kullanabilir. Bu tür "sihirli" içerik türlerini kullanan yapılandırmalarda SetHandler veya AddHandler kullanımından kaçınılmalıdır.

GprofDir Yönergesi

Açıklama: | gmon.out ayrıntılı inceleme verisinin yazılacağı dizin
Sözdizimi: | GprofDir /tmp/gprof/|/tmp/gprof/%
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Sunucu gprof ayrıntılı inceleme desteği ile derlenmişse, GprofDir yönergesi gmon.out dosyalarının süreç çıktığında belirtilen dizine yazılmasını sağlar. Eğer değiştirge bir yüzde simgesi ('%') ile bitiyorsa her süreç kimliği için alt dizinler oluşturulur.

Bu yönerge şimdilik sadece prefork MPM'i ile çalışmaktadır.

HostnameLookups Yönergesi

Açıklama: | İstemci IP adresleri üzerinde DNS sorgularını etkin kılar.
Sözdizimi: | HostnameLookups On|Off|Double
Öntanımlı: | HostnameLookups Off
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core

Bu yönerge oturum açabilecek konak isimlerini tespit edebilmek için DNS sorgularını etkin kılar (ve sonuç REMOTE_HOST’ta belirtilerek CGI/SSI’lere aktarılır). Double değeri sorgunun çift yönlü yapılacağını belirtir. Yani, bir tersine sorgunun ardından bir normal sorgu yapılır. Normal sorguda elde edilen IP adreslerinden birinin istek yapan IP adresi ile eşleşmesi gerekir. ("tcpwrappers" terminolojisinde buna PARANOID adı verilir.)

Konak ismine göre erişimi denetlemek için mod_authz_host kullanıldığında, nasıl bir ayar yapıldığına bakılmaksızın, çift yönlü sorgulama yapılır. Bu güvenlik için gereklidir. Bunun dışında açıkça HostnameLookups Double belirtilmedikçe genellikle çift yönlü sorgulama yapılmaz. Örneğin, sadece HostnameLookups On belirtilmiş ve konak ismi kısıtlamalarıyla korunmuş bir nesne için bir istek yapılmışsa çift yönlü sorgunun başarısına bakılmaksızın CGI’lere REMOTE_HOST olarak tek yönlü sorgu sonucu aktarılır.

Gerçekte ters yönlü sorguya gerek duyulmayan sitelerde ağ trafiğini yormamak için Off, öntanımlı değerdir. Ayrıca, son kullanıcıların DNS sorguları nedeniyle gereksiz yere bir beklemeye maruz kalmaması için de bu daha iyidir. Yükü zaten ağır olan sitelerde, DNS sorgularının görece uzun zaman alması nedeniyle bu yönergenin değeri Off olarak bırakılmalıdır. Öntanımlı olarak kurulum dizininizin bin alt dizinine kurulan logresolve uygulaması kullanılarak oturum açan IP adresleri için isim sorguları çevrim dışıyken yapılabilir.

Son olarak, konak ismine dayalı Require yönergelerine sahipseniz konak ismi araması HostnameLookups ayarına bakılmaksızın gerçekleştirilecektir.

<If> Yönergesi

Açıklama: | Çalışma anında bir koşul bir istek tarafından yerine getirildiği takdirde uygulanacak yönergeleri barındırır.
Sözdizimi: | <If ifade> ... </If>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<If> yönergesi bir ifadeyi çalışma anında değerlendirir ve ifadenin sonucu doğru olduğu takdirde içerdiği yönergeleri uygular. Örnek:

<If "-z req('Host')">

Bir Host: başlığı içermeyen HTTP/1.0 istekleriyle eşleşir. İfadeler, dizge karşılaştırması (==, !=, <, ...), tamsayı karşılaştırması (-eq, -ne, ...) ve diğerleri (-n, -z, -f, ...) için kabuktakilere benzer çeşitli işleçler içerebilir. Ayrıca, düzenli ifadeleri,

<If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/">

kabuk tarzı kalıp eşleştirme ve birçok başka işlemi kullanmak da mümkündür. Bu işlemler istek başlıklarında (req), ortam değişkenlerinde (env) ve çok sayıda başka niteliklerin üstünde yapılabilir. Apache HTTP Sunucusundaki İfadeler belgesinde daha ayrıntılı bilgi bulabilirsiniz.

Bu yapılandırma bölümünün içinde sadece dizin bağlamını destekleyen yönergeler kullanılabilir.

<If> sonrasında atanan CONTENT_TYPE gibi belli değişkenler ve diğer yanıt başlıkları zaten yorumlanmış olacaklarından bu yönerge için kullanılabilir olmayacaktır.

Ayrıca bakınız:

  • Apache HTTP Sunucusundaki İfadeler belgesinde daha ayrıntılı bilgi ve örnek bulabilirsiniz.
  • <ElseIf>
  • <Else>
  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız. <If>, <ElseIf> ve <Else> son olarak uygulanır.

<IfDefine> Yönergesi

Açıklama: | Başlatma sırasında bir doğruluk sınamasından sonra işleme sokulacak yönergeleri sarmalar.
Sözdizimi: | <IfDefine [!]parametre-adı> ... </IfDefine>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

<IfDefine sınama>...</IfDefine> bölümü koşullu olarak işleme sokulacak yönergeleri içerir. Bir <IfDefine> bölümü içindeki yönergeler sadece sınama doğru sonuç verirse işleme sokulur. Aksi takdirde, bölüm içinde kalan her şey yok sayılır.

<IfDefine> bölüm yönergesinde sınama için belirtilebilecek iki biçim vardır:

  • parametre-adı
  • !parametre-adı

Birinci durumda bölüm içinde kalan yönergeler sadece parametre-adı ile belirtilen parametre tanımlı ise işleme sokulur. İkinci durumda ise tersi yapılır, yani sadece parametre-adı ile belirtilen parametre tanımlı değil ise yönergeler işleme sokulur.

parametre-adı argümanı sunucu başlatılırken httpd komut satırında -Dparametre ile veya Define yönergesi ile belirtilerek tanımlı hale getirilebilir.

<IfDefine> bölümleri iç içe olabilir, dolayısıyla çok parametreli basit sınamalar gerçeklenebilir. Örnek:

httpd -DReverseProxy -DUseCache -DMemCache ...

<IfDefine ReverseProxy>
  LoadModule proxy_module   modules/mod_proxy.so
  LoadModule proxy_http_module   modules/mod_proxy_http.so
  <IfDefine UseCache>
    LoadModule cache_module   modules/mod_cache.so
    <IfDefine MemCache>
      LoadModule mem_cache_module   modules/mod_mem_cache.so
    </IfDefine>
    <IfDefine !MemCache>
      LoadModule cache_disk_module   modules/mod_cache_disk.so
    </IfDefine>
  </IfDefine>
</IfDefine>

<IfModule> Yönergesi

Açıklama: | Belli bir modülün varlığına veya yokluğuna göre işleme sokulacak yönergeleri sarmalar.
Sözdizimi: | <IfModule [!]modül-dosyası|modül-betimleyici> ... </IfModule>
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Modül betimleyiciler 2.1 sürümünde ve sonrası için geçerlidir.

<IfModule sınama>...</IfModule> bölümü belli bir modülün varlığına veya yokluğuna göre işleme sokulacak yönergeleri içerir. Bir <IfModule> bölümü içindeki yönergeler sadece sınama doğru sonuç verirse işleme sokulur. Aksi takdirde, bölüm içinde kalan her şey yok sayılır.

<IfModule> bölüm yönergesinde sınama için belirtilebilecek iki biçim vardır:

  • modül
  • !modül

Birinci durumda bölüm içinde kalan yönergeler sadece modül ile belirtilen modül Apache httpd içine dahil edilmişse veya LoadModule yönergesi ile devingen olarak yüklenmişse işleme sokulur. İkinci durumda ise tersi yapılır, yani sadece modül içerilmiş değil ise yönergeler işleme sokulur.

modül argümanında bir modül betimleyici veya modülün derleme sırasındaki dosya adı belirtilebilir. Örneğin, rewrite_module bir betimleyici, mod_rewrite.c ise bir dosya ismidir. Eğer modül çok sayıda kaynak dosyasından oluşuyorsa STANDARD20_MODULE_STUFF dizgesini içeren dosyanın ismi kullanılır.

<IfModule> bölümleri iç içe olabilir, dolayısıyla çok parametreli basit sınamalar gerçeklenebilir.

Bu bölümü sadece yapılandırma dosyanızın belli modüllerin varlığına veya yokluğuna bağlı olarak çalışması gerektiği durumlarda kullanmalısınız. Normal işlemlerde yönergelerin <IfModule> bölümlerine yerleştirilmeleri gerekmez.

Include Yönergesi

Açıklama: | Sunucu yapılandırma dosyalarının başka dosyaları içermesini sağlar.
Sözdizimi: | Include dosya-yolu|dizin-yolu|joker
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Dizin kalıbıyla eşleşme ise 2.3.6 ve sonrasında mevcuttur.

Bu yönerge sunucu yapılandırma dosyalarının başka dosyaları içermesini mümkün kılar.

Çok sayıda dosyayı bir kerede alfabetik sırada içermek için yolun dosya ismi ve dizin parçalarında kabuk tarzı (fnmatch()) dosya ismi kalıp karakterleri kullanılabilir. Ayrıca, eğer Include yönergesi bir dosya değil de bir dizin gösteriyorsa Apache httpd bu dizindeki ve alt dizinlerindeki bütün dosyaları okuyacaktır. Bunula birlikte, dizinin bir bütün olarak okutulması önerilmez, çünkü dizinde httpd programının çökmesine sebep olabilecek geçici dosyalar unutulabilir. Bunun yerine, belli bir şablona uyan dosyaları seçebilmek için, örneğin *.conf gibi dosya kalıplarının kullanılmasını öneriyoruz.

Include yönergesi, bir dosya kalıbı ifadesi hiçbir dosyayla eşleşmezse bir hatayla başarısız olacaktır. Eşleşmeyen dosya kalıbı ifadelerinin yoksayılması gerekiyorsa IncludeOptional yönergesi kullanılabilir.

Dosya yolu mutlak bir dosya yolu olarak belirtilebileceği gibi ServerRoot dizinine göreli olarak da belirtilebilir.

Örnekler:

Include /usr/local/apache2/conf/ssl.conf
Include /usr/local/apache2/conf/vhosts/*.conf

Veya dizinler ServerRoot dizinine göre belirtilebilir:

Include conf/ssl.conf
Include conf/vhosts/*.conf

Dosya kalıbı karakterleri yolun dizin ve dosya parçalarına yerleştirilebilir. conf/vhosts altında en azından bir *.conf içeren hiçbir alt dizin yoksa bu örnek başarısız olacaktır:

Include conf/vhosts/*/*.conf

Bunun yerine, dizin ve dosyaların eksikliği durumunda aşağıdaki komut sadece yoksayılır:

IncludeOptional conf/vhosts/*/*.conf

Ayrıca bakınız:

  • IncludeOptional
  • apachectl

IncludeOptional Yönergesi

Açıklama: | Diğer yapılandırma dosyalarının sunucu yapılandırma dosyasına dahil edilmesini sağlar
Sözdizimi: | IncludeOptional dosya-yolu|dizin-yolu|joker
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | 2.3.6 ve sonrasına kullanılabilmektedir.

Bu yönerge, diğer yapılandırma dosyalarının sunucu yapılandırma dosyasında içerilmesini sağlar. Çalışması Include yönergesi ile bir istisna dışında aynıdır. Dosya kalıp karakterlerinin hiçbir dosya veya dizinle eşleşmemesi durumunda IncludeOptional yönergesi bir hataya sebep olmak yerine bunu sadece yoksayacaktır.

Ayrıca bakınız:

  • Include
  • apachectl

KeepAlive Yönergesi

Açıklama: | HTTP kalıcı bağlantılarını etkin kılar
Sözdizimi: | KeepAlive On|Off
Öntanımlı: | KeepAlive On
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Keep-Alive yönergesi HTTP/1.0 protokolüne bir eklenti olup HTTP/1.1 protokolünün kalıcı bağlantı özelliği aynı TCP bağlantısı üzerinden çok sayıda isteğin gönderilmesini mümkün kılan uzun süreli HTTP oturumları açılmasını sağlar. Bunun, çok sayıda resim içeren HTML belgelerin yanıt zamanlarında bazı durumlarda %50’lik bir hızlanmayla sonuçlandığı gösterilmiştir. Kalıcı bağlantıları etkin kılmak için yönerge KeepAlive On şeklinde kullanılır.

HTTP/1.0 istemcileri için kalıcı bağlantılar sadece bir istemci tarafından özellikle istendiği takdirde kullanılabilir. Ek olarak, HTTP/1.0 istemci kalıcı bağlantıları sadece içerik uzunluğu baştan bilindiği zaman kullanılabilir. Bu, CGI çıktısı, SSI sayfaları ve sunucunun ürettiği dizin listeleri gibi genellikle HTTP/1.0 istemcilere kalıcı bağlantılar kullanmayan devingen içeriklere uygulanır. HTTP/1.1 istemciler için kalıcı bağlantılar aksi belirtilmedikçe öntanımlıdır. İstemci istediği takdirde, uzunluğu bilinmeyen içerik kalıcı bağlantılar üzerinden gönderilirken parçalı kodlama kullanılacaktır.

Bir istemci kalıcı bağlantı kullandığı takdirde, bağlantı üzerinden kaç istek gönderilirse gönderilsin, MaxConnectionsPerChild yönergesi bakımından tek bir istek olarak değerlendirilir.

Ayrıca bakınız:

  • MaxKeepAliveRequests

KeepAliveTimeout Yönergesi

Açıklama: | Bir kalıcı bağlantıda sunucunun bir sonraki isteği bekleme süresi
Sözdizimi: | KeepAliveTimeout sayı[ms]
Öntanımlı: | KeepAliveTimeout 5
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Sunucunun kalıcı bir bağlantıyı kapatmadan önce bir sonraki isteği kaç saniye bekleyeceğini belirler. Ayrıca, ms soneki kullanılarak süreyi milisaniye olarak belirtmek de mümkündür. İstek alındıktan sonra Timeout yönergesiyle belirtilen zaman aşımı değeri uygulanır.

KeepAliveTimeout için yüksek bir değer belirtmek ağır yüklü sunucularda başarım sorunlarına yol açar. Daha yüksek bir zaman aşımı, boştaki istemcilerin bulunduğu bağlantıları bekleyen daha fazla sunucu sürecini meşgul edecektir.

İsme dayalı sanal konak için KeepAliveTimeout atanmamışsa, yerel IP adresi ve portu ile en iyi eşleşen ilk sanal konağın değeri kullanılır.

<Limit> Yönergesi

Açıklama: | Erişimi sınırlanacak HTTP yöntemleri için erişim sınırlayıcıları sarmalar.
Sözdizimi: | <Limit yöntem [yöntem] ... > ... </Limit>
Bağlam: | dizin, .htaccess
Geçersizleştirme: | AuthConfig, Limit
Durum: | Çekirdek
Modül: | core

Erişim denetleyicileri normalde tüm erişim yöntemleri için etkindir ve olağan olanı da budur. Genel durum olarak, erişim denetim yönergeleri bir <Limit> bölümüne yerleştirilmemelidir.

<Limit> bölümünün amacı, erişim denetleyicilerinin etkilerini belli HTTP yöntemleri için sınırlamaktır. <Limit> bölümü içinde listelenen erişim sınırlamaları, kalan tüm diğer yöntemler için etkisiz olacaktır. Aşağıdaki örnekte, erişim sınırlaması POST, PUT ve DELETE yöntemleri için uygulanmakta, diğer tüm yöntemler korumasız bırakılmaktadır:

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

Birden fazla bölümde kullanılabilecek yöntem isimleri: GET, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK ve UNLOCK. Yöntem isimleri harf büyüklüğüne duyarlıdır. GET yöntemi sınırlanırsa HEAD istekleri de sınırlanmış olur. TRACE yöntemi sınırlanamaz (bkz, TraceEnable).

Erişimi sınarlarken bir <Limit> bölümü yerine daima bir <LimitExcept> bölümünü tercih etmelisiniz, çünkü <LimitExcept> bölümü belirtilen yöntemler dışında kalanlara erişim koruması sağlar.

<Limit> ve <LimitExcept> yönergeleri iç içe olabilirler. Bu durumda, başarılı her <Limit> veya <LimitExcept> seviyesi, erişim denetimlerinin uygulanacağı yöntemlerle sınırlı kalmalıdır.

<Limit> veya <LimitExcept> yönergelerini Require yönergesi ile birlikte kullanılırken, ilk Require yönergesinin bir başka Require yönergesinin varlığından bağımsız olarak isteği başarıyla yetkilendirdiğine dikkat ediniz.

Örneğin, aşağıdaki yapılandırmayı ele alalım; tüm kullanıcılar POST istekleri için yetkilendirilecek ve tüm durumlarda Require group editors yönergesi yoksayılacaktır:

<LimitExcept GET>
  Require valid-user
</LimitExcept>
<Limit POST>
  Require group editors
</Limit>

<LimitExcept> Yönergesi

Açıklama: | İsimleri belirtilenler dışında kalan HTTP yöntemleri için kullanılacak erişim sınırlayıcıları sarmalar.
Sözdizimi: | <LimitExcept yöntem [yöntem] ... > ... </LimitExcept>
Bağlam: | dizin, .htaccess
Geçersizleştirme: | AuthConfig, Limit
Durum: | Çekirdek
Modül: | core

<LimitExcept> ve </LimitExcept> argüman olarak belirtilenler dışında kalan HTTP yöntemleri için kullanılacak erişim sınırlayıcıları gruplamakta kullanılır. Yani, <Limit> bölümünün tersine, standart olsun olmasın bütün yöntemler için erişimi kısıtlamakta kullanılabilir. Daha ayrıntılı bilgi edinmek için <Limit> yönergesinin açıklamasına bakınız.

Örnek:

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

LimitInternalRecursion Yönergesi

Açıklama: | Dahili yönlendirmelerin ve istek içi isteklerin azami sayısını belirler.
Sözdizimi: | LimitInternalRecursion sayı [sayı]
Öntanımlı: | LimitInternalRecursion 10
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Örneğin, özgün istekleri dahili olarak bir CGI betiğine yönlendiren Action yönergesi kullanıldığında bir dahili yönlendirme oluşur. İstek içi istekler ise bazı URI’ler için istek yapıldığında ne olacağını bulmak için Apache httpd’nin kullandığı bir mekanizmadır. Örneğin, mod_dir, DirectoryIndex yönergesinde listelenen dosyalara bakmak için istek içi istekler kullanır.

LimitInternalRecursion yönergesi sunucunun dahili yönlendirmeler ve istek içi isteklerin oluşturduğu döngülerden dolayı çökmemesini sağlar. Böyle döngüler genellikle yanlış yapılandırma sonucu ortaya çıkarlar.

Yönerge her istek için değerlendirmeye alınacak iki farklı sınırlama için kullanılabilir. İlk sayı ardarda gelebilen dahili yönlendirmelerin azami sayısını, ikinci sayı ise istek içi isteklerin ne kadar iç içe olabileceğini belirler. Tek bir sayı belirtilirse iki sınırlama için de aynı değer kullanılır.

LimitInternalRecursion 5

LimitRequestBody Yönergesi

Açıklama: | İstemci tarafından gönderilen HTTP istek gövdesinin toplam uzunluğunu sınırlar.
Sözdizimi: | LimitRequestBody bayt-sayısı
Öntanımlı: | LimitRequestBody 0
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

Bu yönerge, bir istek gövdesinde izin verilen bayt sayısını 0 (sınırsız anlamında) ile 2147483647 (2GB) arasında sınırlamak için kullanılır. Vekil isteklerinin snırlı uygulanabilirliği için aşağıdaki nota bakınız.

LimitRequestBody yönergesi kullanıcıya yönergenin kullanıldığı bağlam (sunucu, belli bir dizin, belli bir dosya, belli bir yer) dahilinde bir HTTP istek iletisi gövdesinin izin verilen uzunluğu için bir sınır belirleme imkanı verir. Eğer istemcinin isteği bu sınırı aşarsa sunucu isteği sunmak yerine bir hata iletisi döndürecektir. Normal bir istek ileti gövdesinin uzunluğu büyük oranda özkaynağın doğasına ve bu özkaynak üzerinde izin verilen yöntemlere bağlıdır. CGI betikleri genellikle ileti gövdesini form bilgisini almak için kullanır. PUT yöntemi gerçeklenimleri, en azından, sunucunun o özkaynak için kabul etmek isteyeceği herhangi bir gösterim kadar büyük bir değer gerektirecektir.

Bu yönerge, bazı hizmet reddi (DoS) saldırılarından kaçınmak için sunucu yöneticilerine, anormal istemci istekleri üzerinde daha iyi denetim imkanı sağlar.

Eğer, örneğin, belli bir yere dosya yükleme izni verir ve buraya yüklenebilecek dosya boyutunu 100 kB ile sınırlamak isterseniz yönergeyi şöyle kullanabilirsiniz:

LimitRequestBody 102400

Bu yönergenin vekil istekleri tarafından nasıl yorumlandığı mod_proxy belgesinde ayrıntılı olarak açıklanmıştır.

LimitRequestFields Yönergesi

Açıklama: | İstemciden kabul edilecek HTTP isteği başlık alanlarının sayısını sınırlar.
Sözdizimi: | LimitRequestFields sayı
Öntanımlı: | LimitRequestFields 100
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

sayı, en küçük 0 (sınırsız anlamında), en büyük 32767 olabilir. Öntanımlı değer bir derleme zamanı sabiti olan DEFAULT_LIMIT_REQUEST_FIELDS ile belirlenir (dağıtımla gelen değeri 100’dür).

LimitRequestFields yönergesi sunucu yöneticilerine bir HTTP isteğinde izin verilen istek başlık alanlarının sayısı üzerindeki sınırı değiştirebilme imkanı verir. Sunucu bu değerin, normal bir istemci isteğinin içerebileceği alan sayısından daha büyük olmasına ihtiyaç duyar. Bir istemci tarafından kullanılan istek başlık alanlarının sayısı nadiren 20’yi geçer, fakat bu farklı istemci gerçeklenimleri için değişiklik gösterir ve çoğunlukla kullanıcının tarayıcısını ayrıntılı içerik müzakeresini desteklemek için nasıl yapılandırdığıyla ilgilidir. İsteğe bağlı HTTP eklentileri çoğunlukla istek başlık alanları kullanılarak ifade edilir.

Bu yönerge, bazı hizmet reddi (DoS) saldırılarından kaçınmak için sunucu yöneticilerine, anormal istemci istekleri üzerinde daha iyi denetim imkanı sağlar. Eğer normal istemciler sunucudan istekte bulunurken çok fazla başlık alanı gönderildiğine dair bir hata iletisi alırlarsa bu değerin arttırılması gerekir.

Örnek:

LimitRequestFields 50

Uyarı

İsme dayalı sanal konaklar kullanıldığında, bu yönergenin değeri, yerel IP adresi ve port çifti için öntanımlı olan (listedeki ilk) sanal konaktan alınır.

.

LimitRequestFieldSize Yönergesi

Açıklama: | İstemciden kabul edilecek HTTP isteği başlık uzunluğunu sınırlar.
Sözdizimi: | LimitRequestFieldSize bayt-sayısı
Öntanımlı: | LimitRequestFieldSize 8190
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Bu yönerge, HTTP istek başlığında izin verilecek bayt sayısını belirler.

LimitRequestFieldSize yönergesi, sunucu yöneticilerine HTTP istek başlık alanının azami uzunluğunu ayarlama imkanı verir. Sunucu bu değerin, normal bir istemci isteğinin içerebileceği herhangi bir başlık alanını tutabilecek kadar büyük olmasını gerektirir. Normal bir istek başlık alanı uzunluğu kullanıcının tarayıcısını ayrıntılı içerik müzakeresini desteklemek için nasıl yapılandırdığıyla ilgilidir. SPNEGO kimlik doğrulama başlıkları 12392 baytlık olabilir.

Bu yönerge, bazı hizmet reddi (DoS) saldırılarından kaçınmak için sunucu yöneticilerine, anormal istemci istekleri üzerinde daha iyi denetim imkanı sağlar.

Örnek:

LimitRequestFieldSize 4094
Normal şartlar altında öntanımlı değer değiştirilmemelidir. Ayrıca, kaynak kodu değiştirip yeniden derlemeden bu değeri 8190'dan büyük yapamazsınız.

Uyarı

İsme dayalı sanal konaklar kullanıldığında, bu yönergenin değeri, yerel IP adresi ve port çifti için öntanımlı olan (listedeki ilk) sanal konaktan alınır.

LimitRequestLine Yönergesi

Açıklama: | İstemciden kabul edilecek HTTP istek satırının uzunluğunu sınırlar.
Sözdizimi: | LimitRequestLine bayt-sayısı
Öntanımlı: | LimitRequestLine 8190
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Bu yönerge, HTTP istek satırında izin verilecek bayt sayısını belirler.

LimitRequestLine yönergesi, sunucu yöneticilerine bir istemcinin HTTP istek satırının azami uzunluğunu ayarlama imkanı verir. İstek satırının içeriği HTTP yöntemi, URI ve protokol sürümünden oluştuğundan LimitRequestLine yönergesi, sunucudan bir istek için kullanılan istek adresinin uzunluğunu sınırlamış olur. Sunucu bu değerin, bir GET isteğinin sorgu kısmında aktarılabilen her bilgi dahil, özkaynak isimlerinden her birini tutabilecek kadar büyük olmasını gerektirir.

Bu yönerge, bazı hizmet reddi (DoS) saldırılarından kaçınmak için sunucu yöneticilerine, anormal istemci istekleri üzerinde daha iyi denetim imkanı sağlar.

Örnek:

LimitRequestLine 4094
Normal şartlar altında öntanımlı değer değiştirilmemelidir.

Uyarı

İsme dayalı sanal konaklar kullanıldığında, bu yönergenin değeri, yerel IP adresi ve port çifti için öntanımlı olan (listedeki ilk) sanal konaktan alınır.

LimitXMLRequestBody Yönergesi

Açıklama: | Bir XML temelli istek gövdesinin uzunluğunu sınırlar.
Sözdizimi: | LimitXMLRequestBody bayt-sayısı
Öntanımlı: | LimitXMLRequestBody 1000000
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

Bir XML temelli istek gövdesinin azami bayt sayısını belirler. Değer olarak 0 belirtildiğinde herhangi bir boyut sınaması yapılmaz.

Örnek:

LimitXMLRequestBody 0

<Location> Yönergesi

Açıklama: | İçerdiği yönergeler sadece eşleşen URL’lere uygulanır.
Sözdizimi: | <Location "URL-yolu|URL"> ... </Location>
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

<Location> bölüm yönergesi kapsadığı yönergelerin etki alanını belirtilen URL’lerle sınırlar. Bu yönerge, <Directory> yönergesine benzer ve </Location> yönergesi ile biten bir alt bölüm başlatır. <Location> bölümleri yapılandırma dosyasında göründükleri sıraya göre, <Directory> bölümleri ve .htaccess dosyaları okunup <Files> bölümleri de işlendikten sonra işleme sokulurlar.

<Location> bölümleri dosya sisteminin tamamen dışında işlem görürler. Bunun çeşitli sonuçları olur. En önemlisi, <Location> yönergelerinin dosya sistemi konumlarına erişimi denetim altına almak için kullanılmaması gerekliliğidir. Aynı dosya sistemi konumuna farklı URL’lerle erişmek mümkün olduğundan bu tür erişim denetimleri hile ile atlatılabilir olacaktır.

URL'nin yol bileşeni aşağıdaki koşullardan herhangi birini sağlıyorsa sarmalanan yönergeler isteğe uygulanır:

  • Belirtilen yer URL'nin yol bileşeni ile tam olarak eşleşiyordur.
  • Belirtilen yer bir bölü çizgisi öncesinde bitiyorsa URL'nin yol bileşeninin öneklerinden biriyle eşleşiyordur (bağlamsal bir kök dizin olarak).
  • Belirtilen yer bir bölü çizgisi ile bitiyorsa URL'nin yol bileşeninin öneklerinden biriyle eşleşiyordur (bağlamsal bir kök dizin olarak).

Aşağıdaki örnekte yer belirtimi bir bölü çizgisi ile bitirilmemiştir. /private1, /private1/ ve /private1/file.txt istekleri için sarmalanan yönergeler uygulanacaktır, fakat /private1other isteğine uygulanmayacaktır.

<Location "/private1">
    #  ...
</Location>

Aşağıdaki örnekte yer belirtimi bir bölü çizgisi ile bitirilmiştir. /private2/ ve /private2/file.txt istekleri için sarmalanan yönergeler uygulanacaktır, fakat /private2 ve /private2other isteklerine uygulanmayacaktır.

<Location "/private2/">
    # ...
</Location>

<Location> ne zaman kullanılmalı

<Location> yönergesini dosya sistemi dışındaki içeriğe çeşitli yönergeler uygulamak için kullanın. Dosya sisteminde bulunan içerik için <Directory> ve <Files> bölümlerini kullanın. Bunun istisnası, sunucunun tamamına bir yapılandırma uygulamak için kolay bir yol olan <Location "/"> kullanımıdır.

Kaynağa yapılan (vekil olmayan) tüm istekler için eşleşecek URL, /yol/ şeklinde bir URL yolu olmalı; ne şema, ne konak ismi ne port ne de sorgu dizgesi içermelidir. Vekil istekleri için eşleşecek URL ise şema://sunucuadı/dosya-yolu şeklinde olmalı ve önek içermelidir.

URL içinde dosya kalıp karakterleri kullanılabilir. Dosya kalıp karakterleri bulunan bir dizgede bulunan ? karakteri herhangi bir tek karakterle eşleşirken * karakteri herhangi bir karakter dizisi ile eşleşecektir. URL yolu içindeki / karakterleri ile hiçbir dosya kalıp karakteri eşleşmez.

Ayrıca, ~ karakteri eşliğinde düzenli ifadeler de kullanılabilir. Örneğin,

<Location ~ "/(ek|hususi)/veri">
    #...
</Location>

yönergesi /ek/veri ve /hususi/veri alt dizgeleriyle eşleşecektir. <LocationMatch> yönergesi <Location> yönergesinin düzenli ifade sürümüne eşdeğer davranır ve bir çok yazı tipinde ~ karakterini - karakterinden ayırmak zor olduğu için tercih edilir.

<Location> işlevselliği özellikle SetHandler yönergesi ile birlikte kullanışlı olur. Örneğin, durum isteklerini etkin kılmak ama sadece example.com’dan gelen isteklere izin vermek için şöyle bir uygulama yapabilirsiniz:

<Location "/status">
  SetHandler server-status
  Require host example.com
</Location>

/ (bölü çizgisi) hakkında

Bölü çizgisinin URL içinde bulunduğu yere bağlı olarak özel anlamları vardır. Dosya sistemindeki çok sayıda yanyana kullanımının tek bir bölü çizgisi olarak ele alındığı duruma alışkın olanlar olabilir (yani, /home///foo ile /home/foo aynıdır). URL uzayında bunun böyle olması gerekli değildir. Eğer çok sayıda bölü çizgisini yanyana belirtmeniz gerekiyorsa <LocationMatch> yönergesinde ve <Location> yönergesinin düzenli ifadeli kullanımında bunu açıkça belirtmeniz gerekir.

Örneğin, <LocationMatch "^/abc"> yönergesi /abc ile eşleşecek ama //abc ile eşleşmeyecektir. <Location> yönergesinin düzenli ifade içermeyen kullanımındaki davranış vekil isteklerinde kullanılana benzer ve doğrudan kaynağa yapılan (vekil olmayan) isteklerde çok sayıda bölü çizgisi dolaylı olarak tek bir bölü çizgisiyle eşleşecektir. Örneğin, <Location "/abc/def"> belirtirseniz ve istek /abc//def şeklinde olursa bu ikisi eşleşir.

Ayrıca bakınız:

  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

<LocationMatch> Yönergesi

Açıklama: | İçerdiği yönergeler sadece düzenli ifadelerle eşleşen URL’lere uygulanır.
Sözdizimi: | <LocationMatch düzifade> ... </LocationMatch>
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

<LocationMatch> yönergesi içerdiği yönergelerin etki alanını <Location> yönergesinin yaptığı gibi belirtilen URL’lerle sınırlar. Ancak argüman olarak basit bir dizge değil bir düzenli ifade alır. Örneğin,

<LocationMatch "/(ek|hususi)/veri">
    # ...
</LocationMatch>

yönergesi /ek/veri ve /hususi/veri alt dizgeleriyle eşleşecektir.

Eğer hedef, /ek/veri içeren değil de /ek/veri ile başlayan bir URL ise düzenli ifadenin önüne ^ getirmek gerekir.

<LocationMatch "^/(ek|hususi)/veri">

2.4.8 itibariyle, isimli gruplar ve geriye başvurular elde edilmekte olup ilgili isim büyük harfe çevrildikren sonra "MATCH_" ile öncelendikten sonra ortama yazılmaktadır. Böylece yol elemanlarına mod_rewrite gibi modüllerden veya düzenli ifadelerden başvurmak mümkün kılınmıştır. Karışıklığı önlemek için, numaralı (isimsiz) geriye başvurular yoksayılmaktadır. Bunların yerine isimli geriye başvurular kullanılmalıdır.

<LocationMatch "^/combined/(?<sitename>[^/]+)">
    require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</LocationMatch>

Ayrıca bakınız:

  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

LogLevel Yönergesi

Açıklama: | Hata günlüklerinin ayrıntı seviyesini belirler.
Sözdizimi: | LogLevel [modül:]seviye [modül:seviye] ...
Öntanımlı: | LogLevel warn
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Modül ve dizin bağlamındaki yapılandırmalar Apache HTTP Sunucusunun 2.3.6 ve sonraki sürümlerinde kullanılabilmektedir.

LogLevel yönergesi hata günlüklerine kaydedilen hata iletilerinde hangi ayrıntılara yer verileceğini belirler (ErrorLog yönergesine bakınız). En yüksek önem derecesinden başlayarak olası seviye değerleri aşağıda sıralanmıştır:

Seviye | Açıklama | Örnek
emerg | Acil durumlar - sistem kullanışsız. | "Child cannot open lock file. Exiting" (Alt süreç kilit dosyasını açamıyor. Çıkılıyor)
alert | Ne yapılacaksa beklemeden yapılmalı. | "getpwuid: couldn't determine user name from uid" (getpwuid: Kullanıcı ismi numarasından saptanamadı)
crit | Kriz durumları. | "socket: Failed to get a socket, exiting child" (socket: bir soket alınamadı, alt süreç çıkıyor)
error | Hata durumları. | "Premature end of script headers" (Betik başlıkları beklenmedik şekilde bitti)
warn | Uyarı durumları. | "child process 1234 did not exit, sending another SIGHUP" (1234 alt süreci çıkmadı, başka bir SIGHUP gönderiliyor)
notice | Normal fakat önemli durum. | "httpd: caught SIGBUS, attempting to dump core in ..." (httpd: SIGBUS alındı, core dökümlenmeye çalışılıyor: ...)
info | Bilgilendirme. | "Server seems busy, (you may need to increase StartServers, or Min/MaxSpareServers)..." (Sunucu meşgul görünüyor, (StartServers veya Min/MaxSpareServers değerlerini arttırmanız gerekebilir)...)
debug | Hata ayıklama seviyesi iletileri | "Opening config file ..." (... yapılandırma dosyası açılıyor)
trace1 | İz sürme iletileri | "proxy: FTP: control connection complete" (vekil: FTP: denetim bağlantısı sağlandı)
trace2 | İz sürme iletileri | "proxy: CONNECT: sending the CONNECT request to the remote proxy" (vekil: CONNECT: uzak vekile CONNECT isteği gönderiliyor)
trace3 | İz sürme iletileri | "openssl: Handshake: start"
trace4 | İz sürme iletileri | "read from buffered SSL brigade, mode 0, 17 bytes" (tamponlu SSL gruplamasından okuma, kip 0, 17 baytİz sürme iletileri
trace5 | İz sürme iletileri | "map lookup FAILED: map=rewritemap key=keyname" (eşleşme araması BAŞARISIZ: map=rewritemap key=keyname)
trace6 | İz sürme iletileri | "cache lookup FAILED, forcing new map lookup" (arabellek araması BAŞARISIZ, yeni bir eşleşme araması başlatılıyor)
trace7 | İz sürme iletileri, büyük miktarda veri dökümü | "| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"
trace8 | İz sürme iletileri, büyük miktarda veri dökümü | "| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"

Belli bir seviye belirtildiğinde daha yüksek seviyeden iletiler de raporlanır. Örneğin, LogLevel info belirtildiğinde notice ve warn günlük seviyelerinin iletileri ayrıca raporlanacaktır.

En az crit seviyesinin kullanılması önerilir.

Örnek:

LogLevel notice

Ek Bilgi

Günlük iletileri normal bir dosyaya yazılırken notice seviyesinden iletiler engellenemez ve dolayısıyla daima raporlanırlar. Ancak, günlük kaydı syslog kullanılarak yapılıyorsa bu uygulanmaz.

Bir modül ismi olmaksızın bir seviye belirtmek seviyeyi bu seviyedeki tüm modüller için sıfırlayacaktır. Bir seviyyi bir modül ismiyle birlikte belirtmek seviyeyi sadece bu modül için sıfırlayacaktır. Modül ismi olarak, modülün kaynak dosyası ismini, modül kimliği veya _module sonekli modül ismi belirtmek mümkündür. Yani, aşağıdaki üç belirtim eşdeğerdedir:

LogLevel info ssl:warn
LogLevel info mod_ssl.c:warn
LogLevel info ssl_module:warn

Ayrıca seviyeyi dizin bağlamında değiştirmek de mümkündür:

LogLevel info
<Directory "/usr/local/apache/htdocs/app">
  LogLevel debug
</Directory>
Dizin bağlamında günük seviyesi yapılandırması sadece istek çözümlendikten ve istek dizinle ilişkilendirildikten sonra günlüklenen iletileri etkiler. Bağlantı veya sunucu ile ilişkilendirilmemiş günlük iletileri etkilenmez.

Ayrıca bakınız:

  • ErrorLog
  • ErrorLogFormat
  • Apache HTTP Server Log Files

MaxKeepAliveRequests Yönergesi

Açıklama: | Bir kalıcı bağlantıda izin verilen istek sayısı
Sözdizimi: | MaxKeepAliveRequests sayı
Öntanımlı: | MaxKeepAliveRequests 100
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

MaxKeepAliveRequests yönergesi KeepAlive etkinken bağlantı başına izin verilecek istek sayısını sınırlar. Değer olarak 0 belirtilirse istek sayısı sınırsız olur. Sunucu başarımını yüksek tutmak için yüksekçe bir değer belirtmenizi öneririz.

Örnek:

MaxKeepAliveRequests 500

MaxRangeOverlaps Yönergesi

Açıklama: | Özkaynağın tamamını döndürmeden önce izin verilen üst üste binen aralık sayısı (100-200,150-300 gibi)
Sözdizimi: | MaxRangeOverlaps default | unlimited | none | aralık-sayısı
Öntanımlı: | MaxRangeOverlaps 20
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache HTTP Sunucusunun 2.3.15 ve sonraki sürümlerinde kullanılabilmektedir.

MaxRangeOverlaps yönergesi, sunucunun istemciye göndermeye gönüllü olacağı üst üste binen HTTP Range'lerinin sayısını sınırlar. İzin verilenden daha fazlası istenmişse özkaynağın tamamı döndürülür.

default
Üst üste binen HTTP Range'lerinin sayısını derleme sırasında belirlenen öntanımlı 20 değeriyle sınırlar.
none
Üst üste binen Range başlıkları yoksayılır.
unlimited
Sunucunun sağlamaya gönüllü olacağı üst üste binen HTTP Range'lerinin sayısı sınırlanmaz.
aralık sayısı
Sunucunun sağlamaya gönüllü olacağı üst üste binen HTTP Range'lerinin azami sayısını ifade eden pozitif bir tamsayı.

MaxRangeReversals Yönergesi

Açıklama: | Özkaynağın tamamını döndürmeden önce izin verilen ters sıralı aralık sayısı (100-200,50-70 gibi)
Sözdizimi: | MaxRangeReversals default | unlimited | none | aralık-sayısı
Öntanımlı: | MaxRangeReversals 20
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache HTTP Sunucusunun 2.3.15 ve sonraki sürümlerinde kullanılabilmektedir.

The MaxRangeReversals yönergesi, sunucunun istemciye göndermeye gönüllü olacağı ter sıralı HTTP Range'lerinin sayısını sınırlar. İzin verilenden daha fazlası istenmişse özkaynağın tamamı döndürülür.

default
Ters sıralı HTTP Range'lerinin sayısını derleme sırasında belirlenen öntanımlı 20 değeriyle sınırlar.
none
Ters sıralı Range başlıkları yoksayılır.
unlimited
Sunucunun sağlamaya gönüllü olacağı ters sıralı HTTP Range'lerinin sayısı sınırlanmaz.
aralık-sayısı
Sunucunun sağlamaya gönüllü olacağı ters sıralı HTTP Range'lerinin azami sayısını ifade eden pozitif bir tamsayı.

MaxRanges Yönergesi

Açıklama: | Özkaynağın tamamını döndürmeden önce izin verilen aralık sayısı
Sözdizimi: | MaxRanges default | unlimited | none | aralık-sayısı
Öntanımlı: | MaxRanges 200
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache HTTP Sunucusunun 2.3.15 ve sonraki sürümlerinde kullanılabilmektedir.

MaxRanges yönergesi, sunucunun istemciye göndermeye gönüllü olacağı HTTP Range'lerinin sayısını sınırlar. İzin verilenden daha fazlası istenmişse özkaynağın tamamı döndürülür.

default
HTTP Range'lerinin sayısını derleme sırasında belirlenen öntanımlı 200 değeriyle sınırlar.
none
Range başlıkları yoksayılır.
unlimited
Sunucunun sağlamaya gönüllü olacağı HTTP Range'lerinin sayısı sınırlanmaz.
aralık-sayısı
Sunucunun sağlamaya gönüllü olacağı HTTP Range'lerinin azami sayısını ifade eden pozitif bir tamsayı.

MergeTrailers Yönergesi

Açıklama: | Trailer alanlarının başlığa dahil edilip edilmeyeceğini belirler
Sözdizimi: | MergeTrailers [on|off]
Öntanımlı: | MergeTrailers off
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core
Uyumluluk: | 2.4.11 ve sonrası

Bu yönerge HTTP Trailer alanlarının dahili HTTP başlıklarına kopyalanıp kopyalanmayacağını belirler. Kopyalama işlemi istek gövdesi tamamen alındığında gerçekleşir, çoğu başlık işleminin çok sonra istek başlıklarını inceleme veya değiştirme şansı olur.

Bu seçenek, Trailer alanlarını daima kopyalayan 2.4.11 öncesi dağıtımlarla uyumluluk için vardır.

Mutex Yönergesi

Açıklama: | Muteks mekanizmasını ve kilit dosyası dizinini tüm muteksler veya belirtilenler için yapılandırır
Sözdizimi: | Mutex mekanizma [default|muteks-ismi] ... [OmitPID]
Öntanımlı: | Mutex default
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache HTTP Sunucusunun 2.3.4 ve sonraki sürümlerinde kullanılabilmektedir.

Mutex yönergesi httpd ve diğer modüllerin özkaynaklara erişimi dizgeleştirmekte kullandıkları mekanizmanın yanında isteğe bağlı olarak kilit dosyasının yerini belirler. İlk değiştirge olarak default belirtilirse tüm mutekslerin ayarları değişir; ikinci değiştirge olarak bir muteks ismi belirtilirse (aşağıdaki tabloya bakın) yalnızca bu muteksin öntanımlıları değişir.

Mutex yönergesi genelde aşağıdaki istisnai durumlarda kullanılır:

  • İşlevsel veya başarımsal bir soruna sahip APR tarafından öntanımlı mekanizma seçildiği takdirde muteks mekanizmasını değiştirmek için
  • Öntanımlı dizin, kilitlemeyi desteklemediği takdirde dosya tabanlı muteksler tarafından kullanılan dizini değiştirmek için

Destekleyen modüller

Bu yönerge sadece ap_mutex_register() API'si kullanılarak çekirdek sunucuda imlenmiş muteksleri yapılandırır. httpd ile birlikte dağıtılan tüm modüller Mutex yönergesini destekler, fakat üçüncü parti modüllerin hepsi desteklemeyebilir. Bu yönergenin desteklenip desteklenmediğini öğrenmek için üçüncü parti modülün belgelerini inceleyin; destekliyorsa muteks ad(lar)ı belirtilmiştir.

Kullanılabilen muteks mekanizmaları:

  • default | yes

    APR tarafından saptanan öntanımlı kilitleme gerçeklenimini seçer. Öntanımlı kilitleme gerçeklenimi httpd -V seçeneği ile çalıştırılarak öğrenilebilir.

  • none | no

    Muteksi etkin şekilde iptal eder. Buna bir mutekste izin verilebilmesi için modülün bunun geçerli bir seçim olduğunu belirtmesi gerekir. Daha fazla bilgi için modül belgelerini inceleyin.

  • posixsem

    POSIX semaforuna dayalı bir muteks çeşididir.

    Uyarı

    Süreçteki bir evre muteks parçalama arızalarını tutuyorsa, httpd'nin çökmesi sonucu, semafor sahipliği geri kazanılmaz.

  • sysvsem

    SystemV IPC semaforuna dayalı bir muteks çeşididir.

    Uyarı

    Semafor geri kazanılmadan süreçler çökerse SysV semaforlarının "sızıntı" yapması mümkündür.

    Güvenlik

    Semafor API'si, HTTP sunucusu ile aynı kullanıcı kimliği altında çalışan bir CGI (örn, suexec veya cgiwrapper gibi bir araç kullanmıyorsanız bütün CGI'ler) tarafından hizmet reddi saldırısı yapılmasına izin verir.

  • sem

    POSIX ve SystemV IPC semaforları arasından kullanılabilir "en iyi" semafor gerçeklenimini seçer.

  • pthread

    Süreç çaprazlamalı POSIX evre mutekslerine dayalı bir muteks çeşididir.

    Uyarı

    Çoğu sistemde, bir çocuk süreç bu gerçeklenim tarafından kullanılan bir muteksi tutarken olağandışı bir şekilde sonlanırsa httpd donar ve isteklere yanıt vermeyi durdurur. Bu olduğunda sunucuyu bu durumdan kurtarmak için elle yeniden başlatmak gerekir.

    Bu duruma karşı bir mekanizma sağlayan Solaris ve Linux dikkate değer bir istisnadır. Bu mekanizma, bir muteksi tutan bir çocuk süreç olağandışı bir şekilde sonlandıktan sonra muteksin kurtarılmasını sağlar.

    Sisteminiz POSIX uyumluysa veya pthread_mutexattr_setrobust_np() işlevini sağlıyorsa pthread seçeneğini rahatça kullanabilirsiniz.

  • fcntl:/path/to/mutex

    Muteks olarak fcntl() işlevini ve fiziksel bir (lock-) dosyasını kullanan bir muteks çeşididir.

    Uyarı

    Bu mekanizmaya dayalı çok sayıda muteks, çok evreli ve çok süreçli ortamlarda kullanıldığında, örneğin Solaris'te olduğu gibi fcntl() evrelerden bihaberse, geçerli muteks işlemlerinde donma hataları (EDEADLK) raporlanabilir.

  • flock:/path/to/mutex

    flock() işlevinin dosya kilitlemeyi sağlaması dışında fcntl:/path/to/mutex yöntemine benzer.

  • file:/path/to/mutex

    fcntl ve flock arasından kullanılabilir "en iyi" dosya kilitleme gerçeklenimini seçer.

Çoğu mekanizma, yalnız kendilerini destekleyen platformlarda APR tarafından da destekleniyorsa kullanılabilir. Tüm platformlarda kullanılamayan mekanizmalar posixsem, sysvsem, sem, pthread, fcntl, flock ve file mekanizmalarıdır.

fcntl ve flock dosya tabanlı mekanizmaları ile bir yol sağlandığı takdirde bu, kilit dosyasının oluşturulacağı dizindir. Öntanımlı dizin, httpd'nin çalışma anı dizini ServerRoot'a görelidir. /path/to/mutex için daima bir yerel diskteki dosya sistemi kullanılır, asla NFS- veya AFS gibi bir ağ dosya sistemi kullanılmaz. Dosya ismi daima muteks ismi ile başlar, buna modül tarafından sağlanan isteğe bağlı bir aşama dizgesi eklenebilir, OmitPID değeri belirtilmemişse httpd ebeveyn sürecinin süreç kimliği buna eklenerek dosya ismi eşsiz kılınır. Böylece, çok sayıda httpd süreci aynı kilit dosyası dizinini paylaştığı durumda çakışmalar önlenmiş olur. Örneğin, muteks ismi mpm-accept ise ve kilit dosyası dizini /var/httpd/locks ise ve ebeveyn süreç kimliği 12345 ise bu httpd sürecine ait kilit dosyası ismi /var/httpd/locks/mpm-accept.12345 olurdu.

Güvenlik

Muteks dosyalarını herkesin yazabildiği /var/tmp gibi dizinlere koymaktan kaçınmak en iyisidir. Örneğin, birinin aynı dizinde oluşturmaya çalıştığı bir dosya ile aynı isimde bir kilit dosyasını sunucunun da oluşturmaya çalıştığı durumda sunucu engellenerek bir hizmet reddi saldırısı gerçekleştirilmiş gibi olur.

httpd ve birlikte dağıtılan modüller tarafından kullanılan mutekslerin isimleri:

Muteks ismi | Modül(ler) | Korunan özkaynak
mpm-accept | prefork ve worker MPM'leri | Gürleyen sürü sorunundan kaçınmak için gelen bağlantılar; daha fazla bilgi için başarımın arttırılması belgesine bakın.
authdigest-client | mod_auth_digest | Paylaşımlı bellekteki istemci listesi
authdigest-opaque | mod_auth_digest | Paylaşımlı bellekteki sayaç
ldap-cache | mod_ldap | LDAP sonuç arabelleği
rewrite-map | mod_rewrite | Çoklu isteklerdeki birbirine karışmış G/Ç'tan kaçınmak için harici eşleştirme progamlarıyla iletişim
ssl-cache | mod_ssl | SSL oturum arabelleği
ssl-stapling | mod_ssl | OCSP zımbalama yanıtı arabelleği
watchdog-callback | mod_watchdog | Bir istemci modülünün geri çağırım işlevi

OmitPID seçeneği, httpd ebeveyn süreç kimliğinin kilit dosyası ismine eklenmesini engeller.

Aşağıdaki örnekte, mpm-accept muteksinin mekanizmasının derleme sırasındaki öntanımlısı, kilit dosyasının oluşturulacağı dizinin /var/httpd/locks olarak belirtildiği fcntl mekanizmasıyla değiştirilmektedir.Tüm diğer mutekslerin derleme anı öntanımlı mekanizması ise sysvsem ile değiştirilmektedir.

Mutex sysvsem default
Mutex fcntl:/var/httpd/locks mpm-accept

NameVirtualHost Yönergesi

Açıklama: | ÖNERİLMİYOR: İsme dayalı sanal konaklar için IP adresi belirtir
Sözdizimi: | NameVirtualHost adres[:port]
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

2.3.11 öncesinde, NameVirtualHost yönergesi, isme dayalı sanal konaklar için belli bir IP adresi ve port çiftini sunucuya tanıtmak için gerekliydi. 2.3.11 ve sonrasında, bir IP adresi ve port çifti her zaman çok sayıda sanal konakta kullanılabilmekte, isme dayalı sanal barındırma bu adres için özdevinimli olarak etkin kılınmaktadır.

Bu yönerge şu an etkisizdir.

Ayrıca bakınız:

  • Apache Sanal Konak Belgeleri

Options Yönergesi

Açıklama: | Belli bir dizinde geçerli olacak özellikleri yapılandırır.
Sözdizimi: | Options [+|-]seçenek [[+|-]seçenek] ...
Öntanımlı: | Options FollowSymlinks
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Options
Durum: | Çekirdek
Modül: | core
Uyumluluk: | 2.3.11 sürümünde öntanımlı değer All değiştirilip FollowSymlinks yapıldı.

Options yönergesi belli bir dizinde hangi sunucu özelliklerinin etkin olacağını (veya olmayacağını) belirler.

seçenek olarak hiçbir ek özellik etkin olmayacaksa None, aksi takdirde aşağıdakilerden biri veya bir kaçı belirtilir:

All
MultiViews hariç tüm seçenekler.
ExecCGI
mod_cgi kullanan CGI betiklerinin çalışmasına izin verilir.
FollowSymLinks
Sunucu bu dizindeki sembolik bağları izler. Bu öntanımlıdır.

Sembolik bağlar izlense bile <Directory> bölümleriyle eşleşen dosya yolları değiştirilmez.

FollowSymLinks ve SymLinksIfOwnerMatch Options sadece <Directory> bölümlerinde veya .htaccess dosyaları içinde çalışır.

Sembolik bağ sınamaları, atlatılabilir yarış koşullarına konu olduğundan bu seçeneğin yokluğu bir güvenlik sınırlaması olarak değerlendirilmemelidir.

Includes
mod_include tarafından sağlanan sunucu taraflı içeriklere izin verilir.
IncludesNOEXEC
Sunucu taraflı içeriklere izin verilir fakat #exec cmd ve #exec cgi iptal edilir. Ancak, ScriptAlias’lı dizinlerdeki CGI betikleri için #include virtual hala mümkün olacaktır.
Indexes
İstenen URL bir dizin ile eşleşiyorsa ve bu dizin için bir DirectoryIndex (index.html gibi) belirtilmemişse mod_autoindex bu dizinin biçimlenmiş bir listesini döndürecektir.
MultiViews
mod_negotiation kullanılarak içerik uzlaştırmalı çok görünümlü içeriğe izin verilir.

Bilgi

mod_negotiation karşılaştırmak değerlendirmek için gerçek özkaynaklara ihtiyaç duyduğundan <Directory> yönergesinde belirtilendan farklı bir yer ayarlanırsa bu seçenek yoksayılır.

SymLinksIfOwnerMatch
Sunucu sembolik bağları sadece sembolik bağın hedefi ile bulunduğu dizinin sahibinin aynı kullanıcı olması halinde izleyecektir.

FollowSymLinks ve SymLinksIfOwnerMatch Options sadece <Directory> bölümlerinde veya .htaccess dosyaları içinde çalışır.

Sembolik bağ sınamaları, atlatılabilir yarış koşullarına konu olduğundan bu seçenek bir güvenlik sınırlaması olarak değerlendirilmemelidir.

Normalde, bir dizine çok sayıda Options uygulanabilirse de, dizine en uygun olanı uygulanıp diğerleri yok sayılır; seçenekler katıştırılmaz (bkz, Bölümler Nasıl Katıştırılır?). Bununla birlikte, önüne bir + veya - simgesi konmuş seçenekler varsa, o seçenekler katıştırılır. Önüne + konmuş seçenekler mevcutlara eklenirken - konmuş seçenekler silinir.

Bilgi

+ veya - imli seçenekler içeren Options ile imsiz seçenekler içerenlerin karışık olarak kullanılması aslında geçersiz bir sözdizimi olup sunucunun başlatılması sırasında sözdizimi denetiminin çıkmasıyla reddedilir.

Örneğin, + ve - imleri olmaksızın,

<Directory "/web/docs">
  Options Indexes FollowSymLinks
</Directory>

<Directory "/web/docs/spec">
  Options Includes
</Directory>

yapılandırmasıyla /web/docs/spec dizininde sadece Includes seçeneği etkin olacaktır. Bununla birlikte, ikinci Options yönergesinde + ve - imleri kullanılırsa,

<Directory "/web/docs">
  Options Indexes FollowSymLinks
</Directory>

<Directory "/web/docs/spec">
  Options +Includes -Indexes
</Directory>

yapılandırmasıyla /web/docs/spec dizininde FollowSymLinks ve Includes seçenekleri etkin olacaktır.

Ek Bilgi

-IncludesNOEXEC veya -Includes kullanımı, önceki ayarların ne olduğuna bakılmaksızın sunucu taraflı içeriğin tamamen iptaline sebep olur.

Herhangi bir başka değer belirtilmedikçe FollowSymlinks öntanımlıdır.

Protocol Yönergesi

Açıklama: | Dinlenen bir soket için protokol
Sözdizimi: | Protocol protokol
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache httpd 2.1.5 ve sonrasında kullanılabilmektedir. Windows'ta ise Apache httpd 2.3.3 ve sonrasında kullanılabilmektedir.

Bu yönerge dinlenen belli bir soket için kullanılacak protokolü belirler. Belirtilen protokol bir isteği hangi modülün ele alacağını ve AcceptFilter yönergesiyle yapılan özel eniyilemelere uygulanacak protokolü belirler.

Bir protokol belirtme ihtiyacını sadece standartdışı portlarda çalışıyorsanız duyarsınız. Aksi takdirde, http protokolünün port 80'i, https'in ise 443'ü kullandığı varsayılır.

Örneğin, https'i standartdışı bir portta çalıştırmak isterseniz protokolü şöyle belirtebilirsiniz:

Protocol https

Protokolü Listen yönergesini kullanarak da belirtebilirsiniz.

Ayrıca bakınız:

  • AcceptFilter
  • AcceptFilter
  • Listen

Protocols Yönergesi

Açıklama: | Sunucu/sanal konak için kullanılabilecek protokoller
Sözdizimi: | Protocols protokol ...
Öntanımlı: | Protocols http/1.1
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Sadece Apache 2.4.17 ve sonrasında kullanılabilir.

Bu yönerge bir sunucu/sanal konak için kullanılabilecek protokolleri belirtmekte kullanılır. Bu liste, bir istemcinin bir sanal konak veya sunucu ile uzlaşabilmesini sağlayan prokolleri belirler.

Bir sanal konak veya sunucuda kullanılabilecek protolleri çeşitlendirmek isterseniz bu protokolleri belirtmeniz gerekir. 1.0 ve 0.9 istemcilerle uyumlu olan http/1.1 protokolü öntanımlıdır.

Örneğin, bir sunucunun TLS'li HTTP/2 protokolünü desteklemesini şöyle sağlayabilirsiniz:

Protocols h2 http/1.1

Geçerli protokoller, http ve https bağlantıları için http/1.1 htps bağlantıları için h2 ve http bağlantıları için h2c protokolleridir. Modüller başka protokollerin de etkinleştirilmesini gerektirebilir.

Kullanımından vazgeçilmiş protokollerin silinmesi gerekmez. Böyle protokol isimleri basitçe yoksayılır.

Ana sunucu için belirtilen protokoller, kendi protokol yönergesi olmayan sanal konaklar için de geçerlidir. Diğer yandan sanal konaklarda protokol belirtilmesi ana sunucuda belirtien protollerin bu sanal konaklarda geçersiz olmasına sebep olur.

Ayrıca bakınız:

  • ProtocolsHonorOrder

ProtocolsHonorOrder Yönergesi

Açıklama: | Uzlaşma sırasında protokollerin öncelik sırasını belirler
Sözdizimi: | ProtocolsHonorOrder On|Off
Öntanımlı: | ProtocolsHonorOrder On
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Sadece Apache 2.4.17 ve sonrasında kullanılabilir.

Sunucuda Protocols yönergesinde listelemiş protokollerin mi yoksa istemcinin protokol listesinin mi öncelikli olacağı bu yönerge ile belirtilir.

Off belirtilirse, istemcinin protokol listesi sunucu yapılandırmasındaki sıralamanın önüne geçer.

ProtocolsHonorOrder yönergesine on belirtilirse (öntanımlıdır), istemicinin protokol sıralaması dikkate alınmaz ve protokol uzlaşımının sonucunu sunucu ayarlarındaki sıralama belirler.

Ayrıca bakınız:

  • Protocols

QualifyRedirectURL Yönergesi

Açıklama: | REDIRECT_URL ortam değişkeninin tamamen nitelenmiş olup olmayacağını denetler
Sözdizimi: | QualifyRedirectURL ON|OFF
Öntanımlı: | QualifyRedirectURL OFF
Bağlam: | sunucu geneli, sanal konak, dizin
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Yönerge 2.4.18 ve sonrasında desteklenmektedir. 2.4.17 sürümünde 'QualifyRedirectURL ON' yapılandırması mevcutmuş gibi davranılır.

Bu yönerge sunucuya REDIRECT_URL ortam değişkenin tamamen nitelenmiş olacağını temin eder. Değişken öntanımlı olarak istemci tarafından talep edilen URL'yi harfi harfine içerir, "/index.html" gibi. QualifyRedirectURL ON belirtilseydi aynı istek "http://www.example.com/index.html" gibi bir değerle sonuçlanırdı.

Böyle belirtilmemiş olsa bile, istek tam nitelenmiş bir URL içerseydi REDIRECT_URL de tam nitelenmiş URL'yi içerirdi.

RLimitCPU Yönergesi

Açıklama: | Apache httpd alt süreçleri tarafından çalıştırılan süreçlerin işlemci tüketimine sınırlama getirir.
Sözdizimi: | RLimitCPU saniye|max [saniye|max]
Öntanımlı: | Bir değer belirtilmemiştir; işletim sistemi öntanımlıları kullanılır
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

1 veya 2 değer alır. İlk değer bütün süreçler için sanal özkaynak sınırını, ikinci değer ise kesin özkaynak sınırını belirler. İki değer de birer sayı olabileceği gibi bu sınırın işletim sistemi yapılandırmasında izin verilen üst sınıra ayarlanacağını belirtmek üzere max olabilir. Kesin özkaynak sınırını yükseltmek için sunucunun root olarak veya sistem açılışı sırasında çalıştırılması gerekir.

Bu sınırlar Apache httpd’nin kendi alt süreçlerine değil, isteklere yanıt verirken Apache httpd alt süreçlerinin çatalladıkları süreçlere uygulanır. Bunlar CGI betikleri ve SSI çalıştırma komutları olabilir fakat borulu günlük kaydı gibi ana Apache httpd süreci tarafından çatallanmış süreçler olmazlar.

İşlemci özkaynak sınırları saniye cinsinden ifade edilir.

Ayrıca bakınız:

  • RLimitMEM
  • RLimitNPROC

RLimitMEM Yönergesi

Açıklama: | Apache httpd alt süreçleri tarafından çalıştırılan süreçlerin bellek tüketimine sınırlama getirir.
Sözdizimi: | RLimitMEM bayt-sayısı|max [bayt-sayısı|max]
Öntanımlı: | Bir değer belirtilmemiştir; işletim sistemi öntanımlıları kullanılır
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

1 veya 2 değer alır. İlk değer bütün süreçler için sanal özkaynak sınırını, ikinci değer ise kesin özkaynak sınırını belirler. İki değer de birer sayı olabileceği gibi bu sınırın işletim sistemi yapılandırmasında izin verilen üst sınıra ayarlanacağını belirtmek üzere max olabilir. Kesin özkaynak sınırını yükseltmek için sunucunun root olarak veya sistem açılışı sırasında çalıştırılması gerekir.

Bu sınırlar Apache httpd’nin kendi alt süreçlerine değil, isteklere yanıt verirken Apache httpd alt süreçlerinin çatalladıkları süreçlere uygulanır. Bunlar CGI betikleri ve SSI çalıştırma komutları olabilir fakat borulu günlük kaydı gibi ana Apache httpd süreci tarafından çatallanmış süreçler olmazlar.

Bellek özkaynak sınırları süreç başına bayt sayısı olarak ifade edilir.

Ayrıca bakınız:

  • RLimitCPU
  • RLimitNPROC

RLimitNPROC Yönergesi

Açıklama: | Apache httpd alt süreçleri tarafından çalıştırılabilecek süreç sayısına sınırlama getirir.
Sözdizimi: | RLimitNPROC sayı|max [sayı|max]
Öntanımlı: | Bir değer belirtilmemiştir; işletim sistemi öntanımlıları kullanılır
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

1 veya 2 değer alır. İlk değer bütün süreçler için sanal özkaynak sınırını, ikinci değer ise kesin özkaynak sınırını belirler. İki değer de birer sayı olabileceği gibi bu sınırın işletim sistemi yapılandırmasında izin verilen üst sınıra ayarlanacağını belirtmek üzere max olabilir. Kesin özkaynak sınırını yükseltmek için sunucunun root olarak veya sistem açılışı sırasında çalıştırılması gerekir.

Bu sınırlar Apache httpd’nin kendi alt süreçlerine değil, isteklere yanıt verirken Apache httpd alt süreçlerinin çatalladıkları süreçlere uygulanır. Bunlar CGI betikleri ve SSI çalıştırma komutları olabilir fakat borulu günlük kaydı gibi ana Apache httpd süreci tarafından çatallanmış süreçler olmazlar.

Süreç sayısı sınırı kullanıcı başına süreç sayısına sınırlama getirir.

Ek Bilgi

CGI süreçleri sunucu kullanıcı kimliğinden farklı bir kullanıcı kimliği altında çalışmıyorsa bu yönerge sunucunun kendi oluşturduğu süreç sayısını sınırlayacaktır. Bunun kanıtı error_log’da iletilerin çatallanamamasıdır.

Ayrıca bakınız:

  • RLimitMEM
  • RLimitCPU

ScriptInterpreterSource Yönergesi

Açıklama: | CGI betikleri için yorumlayıcı belirleme tekniği
Sözdizimi: | ScriptInterpreterSource Registry|Registry-Strict|Script
Öntanımlı: | ScriptInterpreterSource Script
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Sadece Win32 için.

Bu yönerge Apache httpd’nin CGI betiklerini çalıştıracak yorumlayıcıyı nasıl tespit edeceğini belirler. Script öntanımlı olup Apache httpd’nin yorumlayıcı olarak betiğin diyezli ünlem satırında (#! ile başlayan ilk satır) belirtilen yorumlayıcıyı kullanacağını belirtir. Win32 sistemlerinde bu satır genellikle şöyledir:

#!C:/Perl/bin/perl.exe

perl yorumlayıcının yeri PATH değişkeninde kayıtlı ise şöyle de olabilir:

#!perl

ScriptInterpreterSource Registry değeri ise betik dosyası uzantısının (.pl gibi) Windows Sicili içindeki HKEY_CLASSES_ROOT ağacında arama yapmak için bir arama anahtarı olarak kullanılmasını sağlar. Betik dosyasını çalıştırmak için tanımlanmış komutu bulmak için Shell\ExecCGI\Command yoluna, orada yoksa Shell\Open\Command yoluna bakılır. İkisi de yoksa son çare olarak Script seçeneğinin davranışına dönülür.

Güvenlik

ScriptAlias’lı dizinlerde Apache httpd bulduğu her dosyayı çalıştırmayı deneyeceğinden ScriptInterpreterSource Registry yapılandırmasını kullanırken dikkatli olun. Registry seçeneği genellikle çalıştırılmayacak dosyalar için istenmeyen program çağrılarına sebep olabilir. Örneğin, çoğu Windows sisteminde .htm dosyaları için ön tanımlı "open" komutu Microsoft Internet Explorer’ın çalıştırılmasına sebep olur; bu bakımdan, betik dizininde bulunan bir .htm dosyası için yapılan bir HTTP isteği tarayıcının sunucu artalanında çalıştırılmasına sebep olacaktır. Bu, sistemi bir kaç dakika içinde çökertmek için iyi bir yoldur.

Registry-Strict seçeneği Apache HTTP Sunucusunun 2.0 sürümünde yeni olup Registry seçeneğinin yaptığını Shell\ExecCGI\Command yolu için yapar. ExecCGI sistem tarafından bilinen bir anahtar olmadığından Windows Siciline elle kaydedilmesi gerekir ve dolayısıyla sisteminiz üzerinde istenmeyen program çağrılarına sebep olmaz.

SeeRequestTail Yönergesi

Açıklama: | İsteğin 63 karakterden büyük olduğu varsayımıyla, mod_status'un ilk 63 karakteri mi yoksa son 63 karakteri mi göstereceğini belirler.
Sözdizimi: | SeeRequestTail On|Off
Öntanımlı: | SeeRequestTail Off
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core
Uyumluluk: | Apache httpd 2.2.7 ve sonrasında kullanılabilmektedir.

mod_status modülü ExtendedStatus On ile işleme alınan asıl isteği gösterir. Tarihsel amaçlarla, isteğin sadece 63 karakteri gösterme amacıyla saklanır. Bu yönerge ilk 63 karakterin mi (önceki davranış ve öntanımlı durum) yoksa son 63 karakterin mi saklanacağını belirler. Bu, şüphesiz, isteğin uzunluğu 64 karakter veya daha fazlaysa uygulanabilirdir.

Apache httpd'ye gelen istek GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1 ise mod_status şunu gösterir:

Off (öntanımlı) | GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples
On | orage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1

ServerAdmin Yönergesi

Açıklama: | Sunucunun hata iletilerinde istemciye göstereceği eposta adresi
Sözdizimi: | ServerAdmin eposta-adresi|URL
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

ServerAdmin yönergesi, sunucunun bir hata durumunda istemciye döndüreceği hata iletilerinde içereceği iletişim adresini belirtmek için kullanılır. Eğer httpd sağlanan değerin bir URL olmadığını saptarsa değerin bir eposta adresi olduğuna hükmeder ve önüne mailto: getirerek onu bir hiper bağ hedefi olarak kullanır. Çoğu CGI betiği bir eposta adresi belirtildiği kabulünü yaptığından değer olarak bir URL değil bir eposta adresi belirtmeniz önerilir. Eğer bir URL belirtecekseniz hedef sizin denetiminizde olan başka bir sunucuda bulunmalıdır, yoksa kullanıcılar hata durumunda bu adrese erişemeyebilirler.

Kullanıcıların sunucu hakkında konuşurken isminizden bahsetmemeleri için burada belirtilecek adresin sırf bu işe adanmış bir adres olması daha iyidir. Örnek:

ServerAdmin www-admin@foo.example.com

ServerAlias Yönergesi

Açıklama: | İstekleri isme dayalı sanal konaklarla eşleştirilirken kullanılacak konak adları için başka isimler belirtebilmeyi sağlar.
Sözdizimi: | ServerAlias konakadı [konakadı] ...
Bağlam: | sanal konak
Durum: | Çekirdek
Modül: | core

ServerAlias yönergesi, istekleri isme dayalı sanal konaklarla eşleştirilirken kullanılacak konak adları için başka isimler belirtebilmeyi sağlar. ServerAlias dosya adı kalıp karakterleri içerebilir.

<VirtualHost *:80>
  ServerName server.example.com
  ServerAlias server server2.example.com server2
  ServerAlias *.example.com
  UseCanonicalName Off
  # ...
</VirtualHost>

İsme dayalı sanal konaklardan en iyi eşleşme kümesinde olanlar yapılandırmada göründükleri sıraya göre işleme sokulur. Joker kullanımları arasında fark gözetilmeksizin ServerName veya ServerAlias yönergesi eşleşen ilk sanal konak kullanılır.

VirtualHost bölümü içindeki isimlerin sırası (jokersiz) ServerAlias yönergesindeki gibi ele alınır.

Ayrıca bakınız:

  • UseCanonicalName
  • Apache HTTP Sunucusu Sanal Konak Belgeleri

ServerName Yönergesi

Açıklama: | Sunucunun özdeşleşeceği konak ismi ve port.
Sözdizimi: | ServerName [şema://]alan-adı|ip-adresi[:port]
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

ServerName yönergesi, sunucunun kendini betimlemekte kullanacağı şema, konak adı ve port değerlerini belirler.

isme dayalı sanal konaklar kullanılırken bir sanal konağı eşsiz bir şekilde betimlemek için ServerName kullanılır (muhtemelen ServerAlias ile birlikte).

Ek olarak, UseCanonicalName yönergesine öntanımlı olmayan bir değer atanarak özüne yönlendiren URL'ler oluştururken de bu yönerge kullanılır.

Örneğin, HTTP sunucusunun barındırıldığı makinenin ismi mail.example.com olduğu halde makinenin bir de www.example.com diye bir de DNS rumuzu varsa ve HTTP sunucunuzun bu rumuzla kendini özdeşleştirmesini isterseniz bunu şöyle belirtebilirsiniz:

ServerName www.example.com

ServerName yönergesi sunucu tanımının içinde herhangi bir yerde görünebilirse de her göründüğü yerde bir öncekini iptal eder.

Bir ServerName ataması yapılmamışsa sunucu istemciye görünen sunucu ismini anlamak için önce işletim sistemine sistemin konak adını sorar. Bu başarılı olmazsa sistem üzerinde IP adresine bir ters DNS sorgusu yapar.

ServerName yönergesinde bir port belirtilmediği takdirde sunucu, isteğin geldiği portu kullanacaktır. Öngörülebilirlik ve güvenilirlik açısından en iyisi ServerName yönergesini kullanarak açıkça bir konak ismi ve port belirtmektir.

İsme dayalı sanal konaklar kullanıyorsanız, <VirtualHost> bölümü içindeki ServerName yönergesi, isteğin Host: başlığında bu sanal konakla eşleşecek konak ismini belirler.

Bazen sunucu, bir ters vekil, yük dengeleyici veya SSL yük aktarım uygulaması gibi bir aygıtın arkasında çalışır. Böyle durumlarda sunucunun kendine yönelik URL’leri doğru üretebildiğinden emin olmak için ServerName yönergesinde istemcinin bağlanacağı https:// şeması ve port numarası belirtilir.

Sunucunun kendine yönelik URL’lerin belirtilen portu içerip içermediğini veya istemcinin yaptığı istekte belirtilen port numarasının verilip verilmediğinin saptamasını sağlayan (örneğin, mod_dir modülü tarafından) ayarlar için UseCanonicalName ve UseCanonicalPhysicalPort yönergelerinin açıklamalarına bakınız.

ServerName yönergesine isim atamadaki bir başarısızlık, sunucu başlatılırken isim bir IP adresine çözümlenebileceğinden bir uyarı çıktılanmasına sebep olur. httpd böyle bir durumda sistemin hostname komutunu kullanarak saptadığı konak ismini kullanacaktır. Bu konak ismi hemen hemen daima sizin istediğiniz isim olmayacaktır.

httpd: Could not reliably determine the server's fully qualified domain name, using belgeler.yerel for ServerName

Çevirisi: Sunucunun tamamen nitelenmiş alan adı gerektiği gibi saptanamadı, ServerName için belgeler.yerel kullanılıyor

Ayrıca bakınız:

  • DNS ile ilgili konular ve Apache HTTP Sunucusu
  • Apache HTTP Sunucusu Sanal Konak Belgeleri
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • ServerAlias

ServerPath Yönergesi

Açıklama: | Uyumsuz bir tarayıcı tarafından erişilmesi için bir isme dayalı sanal konak için meşru URL yolu
Sözdizimi: | ServerPath URL-yolu
Bağlam: | sanal konak
Durum: | Çekirdek
Modül: | core

ServerPath yönergesi isme dayalı sanal konaklarda kullanmak için konağa meşru bir URL yolu belirler.

Ayrıca bakınız:

  • Apache HTTP Sunucusu Sanal Konak Belgeleri

ServerRoot Yönergesi

Açıklama: | Sunucu yapılandırması için kök dizin
Sözdizimi: | ServerRoot dizin-yolu
Öntanımlı: | ServerRoot /usr/local/apache
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

ServerRoot yönergesi sunucu yapılandırmasını içeren dizinin yerini belirtir. Genellikle conf/ ve logs/ gibi alt dizinler içerir. Include, LoadModule gibi diğer yapılandırma yönergelerindeki göreli yollar bu dizine göre ele alınır.

ServerRoot "/home/httpd"

ServerRoot için öntanımlı yer configure betiğinin --prefix seçeneği ile değiştirilebilir ve sunucunun çoğu üçüncü parti dağıtıcısı öntanımlı yeri yukardakilerden farklı bir yere ayarlar.

Ayrıca bakınız:

  • httpd için -d seçeneği
  • ServerRoot dizininin erişim izinlerinin nasıl ayarlanması gerektiğini öğrenmek için güvenlik ipuçları

ServerSignature Yönergesi

Açıklama: | Sunucu tarafından üretilen belgelerin dipnotunu ayarlar.
Sözdizimi: | ServerSignature On|Off|EMail
Öntanımlı: | ServerSignature Off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | All
Durum: | Çekirdek
Modül: | core

ServerSignature yönergesi, sunucu tarafından üretilen belgelerin (hata iletileri, mod_proxy ftp dizin listeleri, mod_info çıktısı, vs.) altındaki dipnot satırını yapılandırabilmenizi sağlar. Böyle bir dipnot satırın istenmesinin sebebi vekil zincirlerinde istemciye dönen hata iletisinin aslında hangi sunucu tarafından üretildiğini kullanıcıya bildirmektir.

Off değeri öntanımlı değer olup dipnot satırının gösterilmemesini sağlar (Apache-1.2 ve öncesi ile uyumluluk). On değeri, sunucu sürüm numarası ve hizmeti sunan sanal konağın isminden (ServerName) oluşan bir dipnot satırı oluşturulmasını sağlar; EMail değeri bu ikisine ek olarak satıra ServerAdmin ile belirtilen adres için bir "mailto:" bağı ekler.

2.0.44 sürümünden beri sunucu sürüm numarasının ayrıntıları ServerTokens yönergesi ile belirlenmektedir.

Ayrıca bakınız:

  • ServerTokens

ServerTokens Yönergesi

Açıklama: | Server HTTP yanıt başlığını yapılandırır.
Sözdizimi: | ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full
Öntanımlı: | ServerTokens Full
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

Bu yönerge Server HTTP yanıt başlığı alanında istemcilere sunucunun işletim sistemi, sunucuyla derlenmiş modüller, vs. hakkında bilgi verilip verilmeyeceğini belirler.

ServerTokens Full (veya belirtilmezse)
Sunucu şunu gönderir (örnek): Server: Apache/2.4.2 (Unix) PHP/4.2.2 MyMod/1.2
ServerTokens Prod[uctOnly]
Sunucu şunu gönderir (örnek): Server: Apache
ServerTokens Major
Sunucu şunu gönderir (örnek): Server: Apache/2
ServerTokens Minor
Sunucu şunu gönderir (örnek): Server: Apache/2.4
ServerTokens Min[imal]
Sunucu şunu gönderir (örnek): Server: Apache/2.4.2
ServerTokens OS
Sunucu şunu gönderir (örnek): Server: Apache/2.4.2 (Unix)

Bu ayarlama sunucunun tamamını etkiler ve her sanal konak için farklılaştırılamaz.

2.0.44 sürümünden itibaren bu yönerge ServerSignature yönergesi tarafından sunulan bilgiyi de etkilemektedir.

ServerTokens yönergesinde minimal'den azının belirtilmesi önerilmez. Bunun sebebi ara işlemlerle ilgili hata ayıklamasını zorlaştırmasıdır. Ayrıca, Server: başlığının iptal edilmesinin sunucunuzu daha güvenli yapmayacağına dikkat ediniz; "çapraşıklıkla sağlanan güvenlik" düşüncesi gerçekle bağdaşmaz ve güvenliği olumsuz etkiler.

Ayrıca bakınız:

  • ServerSignature

SetHandler Yönergesi

Açıklama: | Eşleşen tüm dosyaların belli bir eylemci tarafından işlenmesine sebep olur.
Sözdizimi: | SetHandler eylemci-ismi|none|ifade
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core
Uyumluluk: | ifade seçeneği 2.4.19 sürümünde eklendi

Bir .htaccess dosyasına veya bir <Directory> ya da <Location> bölümüne yerleştirildiğinde, eşleşen tüm dosyaların, ismi eylemci-ismi ile belirtilen eylemci tarafından çözümlenmesine sebep olur. Örneğin, bir dizin içindeki bütün dosyaların, uzantılarına bakılmaksızın birer imagemap kural dosyası olarak çözümlenmesini istersiniz, bu dizin içindeki bir .htaccess dosyasına şöyle bir satır koyabilirsiniz:

SetHandler imap-file

Başka bir örnek: http://localhost/status gibi bir istek yapıldığında sunucunun bir durum bilgisi göstermesi için httpd.conf dosyasına şöyle bir satır koyabilirsiniz:

<Location "/status">
  SetHandler server-status
</Location>

Bu yönergeyi ayrıca, belli bir dosya uzantısına sahip dosyalara uygun bir eylemci atamak için de kullanabilirsiniz. örnek:

<FilesMatch "\.php$">
    SetHandler application/x-httpd-php
</FilesMatch>

Dizge değerli ifadeler istek öncesi değişkenleri içerecek şekilde düzenlenebilir. Buna ismli düzenli ifadelere yapılan geriye başvurular dahildir:

<LocationMatch ^/app/(?<sub>[^/]+)/>
     SetHandler "proxy:unix:/var/run/app_%{env:MATCH_sub}.sock|fcgi://localhost:8080"
</LocationMatch>

Evvelce tanımlanmış bir SetHandler yönergesini None değeriyle geçersiz hale getirebilirsiniz.

Bilgi

SetHandler yönergesi, öntanımlı eylemcileri geçersiz kıldığından, index dosyaları ve dizinleri belirtmek için URL’nin sonuna bölü çizgisi (/) getirmek şeklindeki normal davranış baskılanır.

Ayrıca bakınız:

  • AddHandler

SetInputFilter Yönergesi

Açıklama: | POST girdilerini ve istemci isteklerini işleyecek süzgeçleri belirler.
Sözdizimi: | SetInputFilter süzgeç[;süzgeç...]
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core

SetInputFilter yönergesi, istemci isteklerini ve sunucu tarafından alındığı takdirde POST girdisini işleyecek süzgeç veya süzgeçleri belirler. Bu, diğer AddInputFilter yönergeleri dahil evvelce tanımlanmış süzgeçlere eklenir.

Birden fazla süzgeç belirtilmek istenirse birbirlerinden noktalı virgüllerle ayrılmalı ve çıktıyı işleyecekleri sıraya uygun olarak sıralanmalıdırlar.

Ayrıca bakınız:

  • Süzgeçler belgesi

SetOutputFilter Yönergesi

Açıklama: | Sunucunun yanıtlarını işleyecek süzgeçleri belirler.
Sözdizimi: | SetOutputFilter süzgeç[;süzgeç...]
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Çekirdek
Modül: | core

SetOutputFilter yönergesi, istemciye gönderilmeden önce sunucunun yanıtlarını işleyecek süzgeçleri belirler. Bu, diğer AddOutputFilter yönergeleri dahil evvelce tanımlanmış süzgeçlere eklenir.

Örneğin, aşağıdaki yapılandırma ile /www/data/ dizinindeki bütün dosyalar sunucu taraflı içerik kapsamında ele alınacaktır.

<Directory "/www/data/">
  SetOutputFilter INCLUDES
</Directory>

Birden fazla süzgeç belirtilmek istenirse birbirlerinden noktalı virgüllerle ayrılmalı ve çıktıyı işleyecekleri sıraya uygun olarak sıralanmalıdırlar.

Ayrıca bakınız:

  • Süzgeçler belgesi

TimeOut Yönergesi

Açıklama: | Bir istek için başarısız olmadan önce belirli olayların gerçekleşmesi için sunucunun geçmesini bekleyeceği süre.
Sözdizimi: | TimeOut saniye
Öntanımlı: | TimeOut 60
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

TimeOut yönergesi Apache httpd’nin aşağıdaki durumlarda G/Ç için bekleyeceği süreyi belirler:

  • Veriyi istemciden okurken, okuma tamponu boş olduğu takdirde bir TCP paketinin gelmesini bekleyeceği süre.

    Yeni bir bağlantıda ilk veri için, sunucuya yeni bağlantıyı aktaran bir AcceptFilter yönergesi ile ilgili yapılandırma ele alınıncaya kadar bu yönerge etkilenmez.

  • Veriyi istemciye yazarken, gönderme tamponu dolu olduğu takdirde bir paket alındısı için beklenecek süre.
  • mod_cgi modülünde, bir CGI betiğinden çıktı için beklenecek süre.
  • mod_ext_filter modülünde, bir süzme işleminden çıktı almak için beklenecek süre.
  • mod_proxy modülünde, ProxyTimeout yönergesi yapılandırılmamışsa öntanımlı zaman aşımı değeri.

TraceEnable Yönergesi

Açıklama: | TRACE isteklerinde davranış şeklini belirler
Sözdizimi: | TraceEnable [on|off|extended]
Öntanımlı: | TraceEnable on
Bağlam: | sunucu geneli, sanal konak
Durum: | Çekirdek
Modül: | core

Bu yönerge çekirdek ve vekil (mod_proxy) sunucuların her ikisi için öntanımlı TRACE davranışını değiştirir. Öntanımlı olan TraceEnable on ile RFC 2616’dan kaynaklanan ve isteğe herhangi bir istek gövdesinin eşlik etmesine izin vermeyen TRACE isteklerine izin verilir. TraceEnable off ile çekirdek ve vekil (mod_proxy) sunucuların her ikisi de TRACE isteklerine yanıt olarak bir 405 (Yönteme izin verilmiyor) hatası döndürür.

TraceEnable extended ile sadece sınama ve tanı koyma amaçlarına yönelik olarak istek gövdelerine izin verilir. Asıl sunucu istek gövdesini 64k ile sınırlar (Transfer-Encoding: chunked kullanılmışsa bölüm başlıkları için 8k daha). Asıl sunucu yanıt gövdesinde tüm başlıkları ve bölüm başlıklarının tamamını yansıtacaktır. Vekil sunucuda ise istek gövdesi için 64k’lık sınır yoktur.

Bilgi

Aksine iddialara rağmen, TRACE bir güvenlik açığı değildir ve iptal etmek için geçerli hiçbir sebep yoktur. Böyle yapmak sunucunuzu uyumsuz yapmaktan başka işe yaramaz.

UnDefine Yönergesi

Açıklama: | Bir değişkeni tanımsız yapar
Sözdizimi: | UnDefine değişken-ismi
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

Define yönergesinde veya httpd'nin -D seçeneğiyle belirtileni geri alır.

Bu yönerge başlatma betiklerinde -D seçeneğinin argümanını değiştirmek gerekmeksizin <IfDefine> bölümlerinin kullanımını değiştirmek için kullanılabilir.

Bu yönerge sanal konak bağlamında desteklenirken, kapsanan sanal konaklar haricinde, değişiklikleri kendisinden sonraki tüm yapılandırma yönergelerinde görünür kılar.

UseCanonicalName Yönergesi

Açıklama: | Sunucunun kendi adını ve portunu nasıl belirleyeceğini ayarlar
Sözdizimi: | UseCanonicalName On|Off|DNS
Öntanımlı: | UseCanonicalName Off
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core

Apache httpd‘nin çoğu durumda özüne yönelik URL‘ler (isteğin tekrar aynı sunucuya yapıldığı bir URL türü) oluşturması gerekir. UseCanonicalName On ile Apache httpd, sunucu için meşru ismi ve portu oluşturmak için ServerName yönergesinde belirtilen ismi ve portu kullanır. Bu isim CGI'lerde SERVER_NAME ve SERVER_PORT değerlerinde ve tüm özüne yönelik URL’lerde kullanılır.

UseCanonicalName Off ile Apache httpd, özüne yönelik URL’leri varsa istemci tarafından sağlanan konak ismini ve portu kullanarak oluşturur; bunlar istemci tarafından sağlanmamışsa yukarıda tanımlanan işleme başvurulur. Bu değerler, isme dayalı sanal konakları gerçekleştirirken kullanılan değerlerle aynı olup aynı istemcilerle kullanılabilir. SERVER_NAME ve SERVER_PORT CGI değişkenleri de istemci tarafından sağlanan isim ve portla oluşturulur.

Bir örnek olarak, iç ağdaki istemcilerin sunucuya www gibi bir kısa isim kullanarak bağlandığı durumu ele alırsak daha yararlı olur. Kullanıcılar bir kısa isim ve bir dizin isminden oluşan ve bir / ile sonlandırılmamış http://www/splat şeklinde bir istek yaparlarsa, Apache httpd onları http://www.example.com/splat/ adresine yönlendirecektir. Eğer kimlik doğrulama da etkinse bu kullanıcının iki defa kimlik doğrulamasına sokulmasına sebep olacaktır (bir kere www için bir kere de www.example.com için; daha fazla bilgi için SSS’ye bakınız). Fakat UseCanonicalName Off olsaydı Apache httpd isteği http://www/splat/ adresine yönlendirecekti.

UseCanonicalName DNS diye üçüncü bir seçenek daha vardır ve istek yaparken Host: başlığını kullanmayan eski istemcileri desteklemek amacıyla IP’ye dayalı sanal konaklarla kullanmak için tasarlanmıştır. Bu seçenek etkin olduğunda Apache httpd, istemciyi özüne yönelik URL’lerle doğru yere bağlamak için sunucu IP adresi üzerinde bir ters DNS sorgusu yapar.

Uyarı

Eğer CGI’ler SERVER_NAME değerleri için önkabuller yapıyorlarsa bu seçenek işlerinin bozulmasına yol açabilir. Aslında istemciler konak ismi olarak istedikleri değeri vermekte özgürdürler. Fakat eğer CGI, özüne yönelik URL’leri oluştururken sadece SERVER_NAME değerini kullanıyorsa bu istendiği gibi çalışacaktır.

Ayrıca bakınız:

  • UseCanonicalPhysicalPort
  • ServerName
  • Listen

UseCanonicalPhysicalPort Yönergesi

Açıklama: | Sunucunun kendi adını ve portunu nasıl belirleyeceğini ayarlar
Sözdizimi: | UseCanonicalPhysicalPort On|Off
Öntanımlı: | UseCanonicalPhysicalPort Off
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Çekirdek
Modül: | core

Apache httpd‘nin çoğu durumda özüne yönelik URL‘ler (isteğin tekrar aynı sunucuya yapıldığı bir URL türü) oluşturması gerekir. Apache httpd UseCanonicalName yönergesine bağlı olarak sunucu için meşru portu oluştururken UseCanonicalPhysicalPort On ile olası port olarak istek tarafından kullanılmakta olan fiziksel portu kullanacaktır. UseCanonicalPhysicalPort Off olduğunda ise geçerli bir port numarası oluşturmak için asıl fiziksel port yerine yapılandırma bilgisi kullanılır.

Ek Bilgi

Fiziksel port kullanımı etkin olduğunda işlemler şu sırayla yürütülür:

UseCanonicalName On
  1. Servername ile sağlanan port
  2. Fiziksel port
  3. Öntanımlı port
UseCanonicalName Off | DNS
  1. Host: başlığından çözümlenen port
  2. Fiziksel port
  3. Servername yönergesinde belirtilen port
  4. Öntanımlı port

UseCanonicalPhysicalPort Off olduğunda işlem sırasında fiziksel port adımları atlanır.

Ayrıca bakınız:

  • UseCanonicalName
  • ServerName
  • Listen

<VirtualHost> Yönergesi

Açıklama: | Sadece belli bir konak ismine ve porta uygulanacak yönergeleri barındırır.
Sözdizimi: | <VirtualHost adres[:port] [adres[:port]] ...> ... </VirtualHost>
Bağlam: | sunucu geneli
Durum: | Çekirdek
Modül: | core

<VirtualHost> ve </VirtualHost> birlikte sadece belli bir sanal konağa uygulanacak yönergeleri sarmalamakta kullanılırlar. Bir sanal konak kapsamında belirtilebilecek her yönerge kullanılabilir. Sunucu belli bir sanal konak üzerindeki bir belge için bir istek aldığında <VirtualHost> bölümünde bulunan yapılandırma yönergelerini kullanır. adres şunlardan biri olabilir, istemlik olarak ikinokta imi ve bir port numarası (veya *) eklenebilir:

  • Sanal konağın IP adresi.
  • Sanal konağın IP adresi için tam nitelenmiş alan adı (önerilmez).
  • Tüm IP adresleri ile eşleşmek üzere * karakteri.
  • * için bir takma ad olarak _default_ dizgesi.
<VirtualHost 10.1.2.3:80>
  ServerAdmin webmaster@host.example.com
  DocumentRoot "/www/docs/host.example.com"
  ServerName host.example.com
  ErrorLog "logs/host.example.com-error_log"
  TransferLog "logs/host.example.com-access_log"
</VirtualHost>

İsteğe bağlı port numarasını belirtmeyi mümkün kılmak için IPv6 adresleri köşeli ayraç içine alınır. IPv6 adresi kullanılan bir örnek:

<VirtualHost [2001:db8::a00:20ff:fea7:ccea]:80>
  ServerAdmin webmaster@host.example.com
  DocumentRoot "/www/docs/host.example.com"
  ServerName host.example.com
  ErrorLog "logs/host.example.com-error_log"
  TransferLog "logs/host.example.com-access_log"
</VirtualHost>

Her sanal konağın ya farklı bir IP adresi ve port ile ya da farklı bir konak ismiyle eşleşmesi gerekir. Birinci durumda sunucu makinesinin çok sayıda adresten IP paketleri kabul edecek şekilde yapılandırılması gerekir. (Eğer makinede çok sayıda ağ arabirimi yoksa bu, işletim sistemi desteklediği takdirde ifconfig alias komutuyla sağlanabilir.)

Ek Bilgi

<VirtualHost> kullanımı Apache httpd’nin dinleyeceği adresler üzerinde belirleyici değildir. Apache httpd’nin doğru adresi dinlediğinden emin olmak için Listen kullanmanız gerekebilir.

Her <VirtualHost> bloku içinde bir ServerName yönergesi mutlaka olmalıdır. Yokluğu halinde "ana" sunucu yapılandırmasındaki ServerName miras alınacaktır.

Bir istek alındığında, sunucu isteği, sadece yerel IP adresi ve port çiftine dayalı en iyi eşleşen ilk <VirtualHost> bölümüne eşler. Joker kullanmayanlar daha yüksek önceliğe sahiptir. IP ve port çiftine dayalı bir eşleşme bulunamazsa istek için ana sunucu yapılandırması kullanılır.

En iyi eşleşen IP adresi ve port çiftini birden fazla sanal konak kullanıyorsa sunucu bu sanal konaklar (liste) arasından istenen konak ismiyle en iyi eşleşeni seçer. Eşleşen hiçbir isme dayalı sanal konak yoksa listedeki IP adresi ile eşleşen ilk sanal konak kullanılır. Bunun sonucu olarak, belirtilen IP adresi ve port çifti için listedeki ilk sanal konak, bu IP adresi ve port çifti için öntanımlı sanal konaktır.

Güvenlik

Günlük dosyalarının sunucuyu çalıştıran kullanıcıdan başka herkes tarafından yazılabilen bir yerde saklanmasından dolayı ortaya çıkabilecek güvenlik sorunları hakkında daha ayrıntılı bilgi için güvenlik ipuçları belgesine bakınız.

Ayrıca bakınız:

  • Apache HTTP Sunucusu Sanal Konak Belgeleri
  • DNS ile İlgili Konular ve Apache HTTP Sunucusu
  • Apache HTTP Sunucusunun belli adresleri ve portları dinlemek üzere yapılandırılması
  • Bir istek alındığında farklı yapılandırma bölümlerinin nasıl bir arada ele alındığının açıklaması için <Directory>, <Location> ve <Files> bölümleri nasıl çalışır? belgesine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mpm_common - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache MPM Ortak Yönergeleri

Açıklama: | Birden fazla Çok Süreçlilik Modülü (MPM) tarafından gerçeklenmiş yönergeler bütünü.
Durum: | MPM

CoreDumpDirectory Yönergesi

Açıklama: | core dosyasını dökümlemek üzere Apache HTTP Sunucusunun geçmeye çalışacağı dizin.
Sözdizimi: | CoreDumpDirectory dizin
Öntanımlı: | Öntanımlı değer için aşağıdaki açıklamaya bakınız
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork

Bu yönerge core dosyasını dökümlemek üzere Apache httpd’nin geçmeye çalışacağı dizini belirler. Eğer işletim sisteminiz, çöken bir sürecin olması durumunda core dosyasını çöken sürecin çalışma dizinine yazacak şekilde yapılandırılmışsa, CoreDumpDirectory yönergesinin değeri olarak, öntanımlı olan ve sunucuyu çalıştıran kullanıcı tarafından yazılamayan ServerRoot dizini yerine başka bir çalışma dizini belirtmek gerekir.

Hata ayıklamak amacıyla bir core dosyası dökümlemek isterseniz farklı bir yer belirtmek için bu yönergeyi kullanabilirsiniz. Eğer işletim sisteminiz çöken bir sürecin olması durumunda core dosyasını çöken sürecin çalışma dizinine yazacak şekilde yapılandırılmamışsa, bu yönergenin bir etkisi olmaz.

Linux üzerinde core dökümlemek

Apache httpd root olarak başlatılıp başka bir kullanıcıya geçilirse Linux çekirdeği, süreç tarafından yazılabilir olsa bile core dökümlemeyi iptal eder. Eğer CoreDumpDirectory yönergesi ile açıkça bir dizin belirtirseniz, Apache httpd (2.0.46 ve sonraki sürümleri), Linux 2.4 ve sonrasında core dökümlemeyi yeniden etkinleştirecektir.

BSD üzerinde core dökümlemek

BSD sistemlerinde (FreeBSD gibi) suid bitli çalıştırılabilirlerin core dökümlemesini etkin kılmak için kern.sugid_coredump değişkenine 1 değerini atayın.

Özel sinyaller

CoreDumpDirectory işlemi sadece belli sinyaller için gerçekleşir: SIGFPE, SIGILL, SIGABORT, SIGSEGV ve SIGBUS.

Bazı işletim sistemlerinde SIGQUIT sinyali de bir core dosyası dökümler ancak bunu CoreDumpDirectory veya EnableExceptionHook işlemi üzerinden yapmaz, dolayısıyla core dosyasının yeri tamamen işletim sisteminin belirlediği yer olur.

EnableExceptionHook Yönergesi

Açıklama: | Bir çöküş sonrası olağandışılık eylemcilerini çalıştıracak kancayı etkin kılar.
Sözdizimi: | EnableExceptionHook On|Off
Öntanımlı: | EnableExceptionHook Off
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork

Güvenlik sebebiyle bu yönerge sadece Apache --enable-exception-hook seçeneği ile yapılandırılmışsa kullanılabilir olacaktır. Bu, harici modüllerin eklenmesine ve bir çocuk sürecin çöküşü sonrası bir şeyler yapmaya izin veren bir kancayı etkin kılar.

Bu kancayı kullanan iki modül (mod_whatkilledus ve mod_backtrace) zaten vardır. bunlar hakkında daha fazla bilgi edinmek için Jeff Trawick'in EnableExceptionHook sitesine bakabilirsiniz.

GracefulShutdownTimeout Yönergesi

Açıklama: | Sunucunun nazikçe kapatılmasının ardından ana süreç çıkana kadar geçecek süre için bir zaman aşımı belirler.
Sözdizimi: | GracefulShutdownTimeout saniye
Öntanımlı: | GracefulShutdownTimeout 0
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork
Uyumluluk: | Sürüm 2.2 ve sonrasında mevcuttur

GracefulShutdownTimeout yönergesi, sunucuya "nazikçe dur" sinyali gönderildikten sonra mevcut bağlantılara hizmet sunmaya daha kaç saniye devam edebileceğini belirtir.

Bu değerin 0 olarak belirtilmesi, sunucunun bekleyen bütün isteklere hizmet sunumu tamamlanıncaya kadar (gerekirse sonsuza kadar) bekleyebileceği anlamına gelir.

Listen Yönergesi

Açıklama: | Sunucunun dinleyeceği IP adresini ve portu belirler.
Sözdizimi: | Listen [IP-adresi:]port-numarası [protokol]
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2
Uyumluluk: | protokol değiştirgesi 2.1.5 sürümünde eklenmiştir.

Listen yönergesi Apache httpd’yi sadece belli IP adreslerini ve portlarını dinlemeye sevkeder. Listen artık belirtilmesi zorunlu yönergelerden biridir. Yapılandırma dosyasında bulunmadığı takdirde sunucu başlatılırken başarısız olacaktır. Bu Apache HTTP Sunucusunun önceki sürümünde böyle değildi.

Listen yönergesi Apache httpd’ye, sadece belli portlardan veya IP adresi ve port çiftlerinden gelen istekleri kabul etmesini söyler. Eğer sadece port numarası belirtilmişse sunucu belirtilen portu bütün ağ arabirimlerinde dinleyecektir. Eğer portla birlikte bir IP adresi de belirtilmişse, sunucu belirtilen portu sadece belirtilen arabirimden dinleyecektir.

Çok sayıda IP adresi ve port belirtmek için çok sayıda Listen yönergesi kullanılabilir. Sunucu bu durumda belirtilen bütün IP adreslerinden ve portlardan gelecek isteklere yanıt verecektir.

Örneğin sunucunun hem port 80 hem de port 8000’den istek kabul etmesini istiyorsanız bunu şöyle belirtebilirsiniz:

Listen 80
Listen 8000

Sunucunun belirtilen iki ağ arabiriminden ve port numarasından gelen bağlantıları kabul etmesi için şu yapılandırmayı kullanabilirsiniz:

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

IPv6 adresleri belirtilirken örnekteki gibi köşeli ayraçlar arasına alınmalıdır:

Listen [2001:db8::a00:20ff:fea7:ccea]:80

İsteğe bağlı protocol argümanı çoğu yapılandırmada gerekli değildir. Belirtilmediği takdirde. port 443 için https ve tüm diğer portlar için http öntanımlıdır. Protokol, isteği hangi modülün elde edeceğinin ve AcceptFilter yönergesi ile protokole özgü hangi en iyilemelerin uygulanacağının saptanmasında kullanılır.

Protokol belirtme ihtiyacını sadece standartdışı portlar çalıştırıyorsanız duyarsınız. Örneğin, port 8443 üzerinde bir https sitesi çalıştırmak istiyorsanız bunu şöyle belirtebilirsiniz:

Listen 192.170.2.1:8443 https

Hata durumu

Aynı IP adresi ve portun çok sayıda Listen yönergesinde belirtilmesi bir "adres kullanımda" (Address already in use) hatasına yol açar.

Ayrıca bakınız:

  • DNS ve Apache ile ilgili Konular
  • Apache HTTP Sunucusunun Kullandığı Adreslerin ve Portların Ayarlanması
  • Address already in use hata iletisinin ve diğer sebeplerin açıklaması

ListenBackLog Yönergesi

Açıklama: | Bekleyen bağlantılar kuyruğunun azami uzunluğunu belirler
Sözdizimi: | ListenBacklog kuyruk-uzunluğu
Öntanımlı: | ListenBacklog 511
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

Bekleyen bağlantılar kuyruğunun azami uzunluğu. Genellikle bu ayar ne gerekir ne de istenir. Ancak bazı sistemlerde TCP SYN yüklenme saldırılarına karşı bu değerin arttırılması gerekebilir. kuyruk-uzunluğu parametresi için listen(2) işlevinin açıklamasına bakınız.

Bu değer çoğunlukla işletim sistemi tarafından daha küçük bir sayıyla sınırlanır. Bu, işletim sistemine bağlı olarak değişiklik gösterir. Ayrıca, çoğu işletim sisteminin kuyruk-uzunluğu parametresi ile ne belirttiğinize bakmaksızın kendisi için atanmış değeri (fakat normal olarak daha büyüğünü) kullanacağına dikkat ediniz.

ListenCoresBucketsRatio Yönergesi

Açıklama: | İşlemci çekirdek sayısının dinleyenlerin buket sayısına oranı
Sözdizimi: | ListenCoresBucketsRatio oran
Öntanımlı: | ListenCoresBucketsRatio 0 (iptal)
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork
Uyumluluk: | Apache HTTP Server 2.4.17 ve sonrasında, SO_REUSEPORT soket seçeneğini destekleyen bir Linux çekirdeğinin varlığında ve yeni bağlantıların bunu kullanan dinleme süreçlerinin (veya evrelerinin) soketleri arasında eşit paylaştırılıyor olması halinde kullanılır. Örneğin Linux 3.9 ve sonrasında kullanılabilirken *BSD'lerin şu anki SO_REUSEPORT gerçeklenimi ile kullanılamaz.

(çevrimiçi) İşlemci çekirdek sayısının dinleyenlerin buket sayısına oranı, Apache HTTP Sunucusunun işlemci_çekirdek_sayısı / oran sayıda dinleme buketi oluşturması için kullanılabilir ve bu buketlerin herbiri aynı portlar üzerinde kendi Listen soketlerini içeriyor olurlar. Bu durumda, her çocuk süreç tek bir buketle çalışır (çocukların oluşturulması sırasında buketler döner dağılımla eşleştirilir).

ListenCoresBucketsRatio yeni bağlantılar kabul edilirken/darboğazlar oluşurken ölçeklenebilirliği arttırabilir. Çok sayıda işlemci çekirdekli sistemlerde bu özelliğin etkinleştirilmesinin önemli başarım artışları ve daha kısa yanıt süreleri oluşturduğu gözlenmiştir.

Bu oranın etkin olabilmesi için işlemci çekirdeği çift sayıda olmalıdır. oran için önerilen değer 8 olup bu durumda çalışma anında en azından 16 çekirdek kullanılabiliyor olmalıdır.

MaxConnectionsPerChild Yönergesi

Açıklama: | Tek bir çocuk sürecin ömrü boyunca işleme sokabileceği istek sayısını sınırlamakta kullanılır.
Sözdizimi: | MaxConnectionsPerChild sayı
Öntanımlı: | MaxConnectionsPerChild 0
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2
Uyumluluk: | Apache HTTP Sunucusunun 2.3.9 ve sonraki sürümlerinde kullanılabilmektedir. Eski isim MaxRequestsPerChild hala desteklenmektedir.

MaxConnectionsPerChild yönergesi, tek bir çocuk sürecin işleme sokabileceği istek sayısını sınırlamakta kullanılır. MaxConnectionsPerChild istekten sonra çocuk süreç ölür. Eğer MaxConnectionsPerChild için 0 belirtilmişse sürecin ömrü sonsuz olacaktır.

MaxConnectionsPerChild için sıfırdan farklı bir değer belirtilmesi sürecin kullanacağı bellek miktarını sınırlamak suretiyle olası bellek sızıntılarını engeller.

MaxMemFree Yönergesi

Açıklama: | free() çağrılmaksızın ana bellek ayırıcının ayırmasına izin verilen azami bellek miktarını belirler.
Sözdizimi: | MaxMemFree kB-sayısı
Öntanımlı: | MaxMemFree 2048
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware

MaxMemFree yönergesi, free() çağrılmaksızın her bellek ayırıcının ayırmasına izin verilen azami bellek miktarını kB cinsinden belirler. Evreli MPM'lerde her evre kendi ayırıcısına sahiptir. 0 değeri belirtildiğinde eşik sınırsız olacaktır.

MaxRequestWorkers Yönergesi

Açıklama: | Aynı anda işleme sokulacak azami bağlantı sayısı
Sözdizimi: | MaxRequestWorkers sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork

MaxRequestWorkers yönergesi aynı anda işleme sokulacak bağlantı sayısını sınırlamak için kullanılır. MaxRequestWorkers bağlantı isteğinden fazlası geldiği takdirde bu istekler normal olarak kuyruğa alınıp bekletilir. Kuyrukta bekletilecek isteklerin azami sayısı ise ListenBacklog yönergesi ile belirlenir. İstek sunmakta olan çocuk süreçlerden biri serbest kaldığında bekletilen bağlantılardan birine hizmet sunulmaya başlanır.

Evreli olmayan sunucularda (prefork gibi) MaxRequestWorkers yönergesi istekleri sunmak için başlatılacak çocuk süreçlerin azami sayısını belirler. Öntanımlı değer 256 olup bu değeri arttırmak isterseniz ServerLimit değerini de arttırmalısınız.

Çok evreli ve melez sunucularda (event veya worker gibi) MaxRequestWorkers yönergesi istemcilere hizmet verecek evre sayısını sınırlar. Öntanımlı değer melez MPM’ler için 16'dır (ServerLimit ile ThreadsPerChild çarpılır: 16 x 25). Bu bakımdan MaxRequestWorkers değerini 16 süreçten fazlasına ayarlamak için ServerLimit değerini de arttırmalısınız.

MaxRequestWorkers yerine 2.3.13 öncesinde MaxClients kullanılırdı. Eski isim hala desteklenmektedir.

MaxSpareThreads Yönergesi

Açıklama: | Boştaki azami evre sayısını belirler
Sözdizimi: | MaxSpareThreads number
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, mpm_netware, mpmt_os2

Boştaki azami evre sayısı. Her MPM bu yönerge karşısında farklı davranır.

worker ve event için MaxSpareThreads 250 öntanımlıdır. Bu MPM'ler boştaki evreleri sunucu genelinde izler. Eğer sunucuda çok fazla boşta evre varsa, sunucu boştaki evrelerin sayısı bu sınırın altına inene kadar çocuk süreçleri öldürür.

mpm_netware için MaxSpareThreads 100 öntanımlıdır. Bu MPM tek bir süreç olarak çalıştığından boştaki evre sayısı aynı zamanda sunucu genelinde boştaki evre sayısıdır.

mpmt_os2 modülü mpm_netware modülü gibi çalışır. mpmt_os2 için öntanımlı değer 10'dur.

Kısıtlamalar

MaxSpareThreads için değer aralığı sınırlıdır. Apache httpd belirtilen değeri aşağıdaki kurallara uygun olarak kendiliğinden düzeltecektir:

  • mpm_netware modülü, değerin MinSpareThreads değerinden küçük olmasını gerektirir.
  • worker ve event için değer, MinSpareThreads ve ThreadsPerChild toplamına eşit veya büyük olmak zorundadır.

Ayrıca bakınız:

  • MinSpareThreads
  • StartServers
  • MaxSpareServers

MinSpareThreads Yönergesi

Açıklama: | İsteklerin ani artışında devreye girecek boştaki evrelerin asgari sayısını belirler.
Sözdizimi: | MinSpareThreads sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, mpm_netware, mpmt_os2

İsteklerin ani artışında devreye girecek boştaki evrelerin asgari sayısı. Her MPM bu yönerge karşısında farklı davranır.

worker ve event modülü için MinSpareThreads 75 öntanımlıdır ve bu modül boştaki evreleri sunucu genelinde izler. Eğer sunucuda boştaki evre sayısı yetersizse, sunucu, boştaki evrelerin sayısı bu sınırın üstüne çıkana kadar çocuk süreç oluşturur.

mpm_netware için MinSpareThreads 10 öntanımlıdır ve tek süreç kendisi olduğundan izleme sunucu genelinde yapılır.

mpmt_os2 modülü mpm_netware modülü gibi çalışır. mpmt_os2 için öntanımlı değer 5'tir.

Ayrıca bakınız:

  • MaxSpareThreads
  • StartServers
  • MinSpareServers

PidFile Yönergesi

Açıklama: | Ana sürecin süreç kimliğinin (PID) kaydedileceği dosyayı belirler.
Sözdizimi: | PidFile dosya
Öntanımlı: | PidFile logs/httpd.pid
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpmt_os2

PidFile yönergesi, sunucunun artalan sürecinin süreç kimliğinin kaydedileceği dosyayı belirler. Dosya ismi mutlak dosya yoluyla belirtilmemişse dosya yolunun ServerRoot dizinine göre belirtildiği kabul edilir.

PidFile /var/run/apache.pid

Sunucuya sinyal gönderebilmek çoğunlukla işe yarar. Böylece ErrorLog ve TransferLog dosyaları kapatılıp yeniden açılır ve yapılandırma dosyaları yeniden okunur. Bu, PidFile dosyasında belirtilen süreç kimliğine bir SIGHUP (kill -1) sinyali gönderilerek yapılır.

Günlük dosyasının yeri ve güvenlik ile ilgili uyarılar PidFile dosyası içinde sözkonusu olabilir.

Ek Bilgi

Apache HTTP Sunucusunu (yeniden) başlatırken veya durdururken sadece apachectl betiğini kullanmanız önerilir.

ReceiveBufferSize Yönergesi

Açıklama: | TCP alım tamponu boyu
Sözdizimi: | ReceiveBufferSize bayt-sayısı
Öntanımlı: | ReceiveBufferSize 0
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

Sunucunun TCP alım tamponu boyunu bayt-sayısı ile belirtilen bayta ayarlar.

0 değeri atarsanız sunucu işletim sistemi öntanımlısını kullanacaktır.

ScoreBoardFile Yönergesi

Açıklama: | Çocuk süreçler için eşgüdüm verisini saklamakta kullanılan dosyanın yerini belirler.
Sözdizimi: | ScoreBoardFile dosya-yolu
Öntanımlı: | ScoreBoardFile logs/apache_runtime_status
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt

Apache HTTP Sunucusu ana ve çocuk süreçler arasında iletişim için bir çetele tutar. Bazı mimariler bu iletişimi kolaylaştırmak için bir dosya gerektirir. Eğer yönerge belirtilmezse Apache httpd çeteleyi önce tamamen bellekte oluşturmayı dener (anonim paylaşımlı bellek kullanarak); bunda başarılı olamazsa dosyayı diskte oluşturmaya çalışacaktır (paylaşımlı belleğe eşlemli dosya kullanarak). Bu yönergenin belirtilmesi Apache httpd'nin dosyayı daima diskte oluşturmasına sebep olur.

ScoreBoardFile /var/run/apache_status

Paylaşımlı belleğe eşlemli dosya, çeteleye doğrudan erişmesi gereken üçüncü parti uygulamalar için yararlıdır.

Eğer ScoreBoardFile yönergesi ile bir dosya belirtecekseniz, dosyayı bir RAM diske yerleştirerek hız artışı sağlayabilirsiniz. Fakat, günlük dosyası yerleştirme ve güvenlik ile ilgili uyarılara benzer uyarılara karşı dikkatli olunuz.

Ayrıca bakınız:

  • Apache HTTP Sunucusunu Durdurma ve Yeniden Başlatma

SendBufferSize Yönergesi

Açıklama: | TCP tamponu boyu
Sözdizimi: | SendBufferSize bayt-sayısı
Öntanımlı: | SendBufferSize 0
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

Sunucu TCP gönderim tamponu boyunu bayt-sayısı ile belirtilen bayta ayarlayacaktır. Yüksek hızlı yüksek yataklık süreli bağlantılarda işletim sisteminin öntanımlı değerini aşacak şekilde (örn, kıtalararası hızlı hatlarda 100ms veya fazlası) ayarlamak çoğunlukla kullanışlıdır.

0 değeri atarsanız sunucu işletim sistemi öntanımlısını kullanacaktır.

İşletim sisteminizin ilaveten yapılandırılması, yüksek hız, yüksek gecikme bağlantılarında daha yüksek başarım elde etmek için gerekli olabilir.

Bazı işletim sistemlerinde, TCP davranışı, EnableSendfile yönergesine Off değeri atanmadıkça görülemeyen, büyükçe bir SendBufferSize değerinden kaynaklanarak değişir. Bu etkileşim sadece duruk dosyalarda görülür.

ServerLimit Yönergesi

Açıklama: | Ayarlanabilir süreç sayısının üst sınırını belirler.
Sözdizimi: | ServerLimit sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork

prefork modülü söz konusu olduğunda bu yönerge, Apache httpd sürecinin ömrü boyunca MaxRequestWorkers yönergesine atanabilecek azami değeri belirler. worker ve event modülü sözkonusu olduğunda ise, Apache httpd sürecinin ömrü boyunca MaxRequestWorkers yönergesine atanabilecek azami değeri ThreadLimit ile birlikte belirler. Bu yönergeyi bir yeniden başlatma sırasında değiştirirseniz bu değişiklik yok sayılır fakat MaxRequestWorkers değişiklikleri dikkate alınır.

Bu yönergenin kullanılması özel bir dikkat gerektirir. Eğer ServerLimit gereğinden yüksek bir değere ayarlanırsa, gereksiz yere paylaşımlı bellek ayrılmış olur. Eğer ServerLimit ve MaxRequestWorkers değerleri sistemin işleyebileceğinden daha yüksek değerlere ayarlanırsa Apache httpd başlayamayacağı gibi sistemi kararsız hale de getirebilir.

Bu yönergeyi prefork modülü ile sadece MaxRequestWorkers yönergesine 256’dan (öntanımlı) daha büyük bir değer atayacaksanız kullanınız. Bu yönergeye MaxRequestWorkers için atamak istediğiniz değerden fazlasını atamayınız.

worker ve event modülü söz konusu olduğunda bu yönergeyi MaxRequestWorkers ve ThreadsPerChild ayarları 16 sunucu sürecinden (16 öntanımlıdır) fazlasını gerektiriyorsa ayarlayınız. Bu yönergeye MaxRequestWorkers ve ThreadsPerChild için gerekli gördüğünüz sunucu süreci sayısından fazlasını atamayınız.

Ek Bilgi

Sunucu içinde derlenmiş olarak ServerLimit 20000 şeklinde bir zorlayıcı sınır vardır (prefork için 200000’dir). Bu önlem, yazım hatalarının istenmeyen sonuçlara yol açmasını engellemek için düşünülmüştür. Bu sınırı daha da arttırmak için mpm kaynak dosyasındaki MAX_SERVER_LIMIT değerini değiştirip sunucuyu yeniden derlemeniz gerekir.

Ayrıca bakınız:

  • Apache HTTP Sunucusunu Durdurma ve Yeniden Başlatma

StartServers Yönergesi

Açıklama: | Sunucunun başlatılması sırasında oluşturulan çocuk süreçlerin sayısını belirler.
Sözdizimi: | StartServers sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, prefork, mpmt_os2

StartServers yönergesi, sunucunun başlatılması sırasında oluşturulan çocuk süreçlerin sayısını belirler. Süreç sayısı normal olarak yüke bağlı olarak değişse de bu değerin ayarlanmasını gerektirecek küçük bir sebep vardır. (MinSpareThreads, MaxSpareThreads, MinSpareServers, MaxSpareServers yönergelerine bakınız.)

Öntanımlı değer MPM’den MPM’e fark eder. Öntanımlı değer worker ve event için 3 iken prefork için 5, mpmt_os2 için 2'dir.

StartThreads Yönergesi

Açıklama: | Sunucunun başlatılması sırasında oluşturulan evrelerin sayısını belirler.
Sözdizimi: | StartThreads sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | mpm_netware

StartThreads yönergesi, sunucunun başlatılması sırasında oluşturulan evrelerin sayısını belirler. Evre sayısı normal olarak yüke bağlı olarak değişse de bu değerin ayarlanmasını gerektirecek küçük bir sebep vardır. (MinSpareThreads, MaxSpareThreads, MinSpareServers, MaxSpareServers yönergelerine bakınız.)

mpm_netware için StartThreads 50 öntanımlı olup, sadece tek bir süreç olduğundan, sunucunun başlatılması sırasında oluşturulan evrelerin toplam sayısı 50’dir.

ThreadLimit Yönergesi

Açıklama: | Çocuk süreç başına ayarlanabilir evre sayısının üst sınırını belirler.
Sözdizimi: | ThreadLimit sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, mpm_winnt

Bu yönerge, Apache httpd sürecinin ömrü boyunca ThreadsPerChild yönergesine atanabilecek azami değeri belirler. Bu yönergeyi bir yeniden başlatma sırasında değiştirirseniz bu değişiklik yok sayılır fakat ThreadsPerChild değişiklikleri dikkate alınır.

Bu yönergenin kullanılması özel bir dikkat gerektirir. Eğer ThreadLimit değeri ThreadsPerChild değerinden yüksek bir değere ayarlanırsa, gereksiz yere paylaşımlı bellek ayrılmış olur. Eğer ThreadLimit ve ThreadsPerChild değerleri sistemin işleyebileceğinden daha yüksek değerlere ayarlanırsa Apache httpd başlayamayacağı gibi sistemi kararsız hale de getirebilir. Bu yönergeye Apache httpd'nin çalışması için öngörülmüş en büyük değerden daha yükseğini atamayınız.

ThreadLimit yönergesinin öntanımlı değeri mpm_winnt için 1920, diğerleri için 64’tür.

Ek Bilgi

Sunucu içinde derlenmiş olarak ThreadLimit 20000 şeklinde bir zorlayıcı sınır vardır (mpm_winnt için 15000, event için ThreadLimit 100000). Bu önlem, yazım hatalarının istenmeyen sonuçlara yol açmasını engellemek için düşünülmüştür. Bu sınırı daha da arttırmak için mpm kaynak dosyasındaki MAX_SERVER_LIMIT değerini değiştirip sunucuyu yeniden derlemeniz gerekir.

ThreadsPerChild Yönergesi

Açıklama: | Her çocuk süreç tarafından oluşturulan evrelerin sayısını belirler.
Sözdizimi: | ThreadsPerChild sayı
Öntanımlı: | Ayrıntılar için aşağıdaki açıklamaya bakınız.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, mpm_winnt

Bu yönerge, her çocuk süreç tarafından oluşturulan evrelerin sayısını belirler. Çocuk süreçler bu evreleri başlatıldıklarında oluştururlar ve bundan daha fazlasını asla oluşturmazlar. mpm_winnt gibi sadece bir çocuk sürecin bulunduğu bir MPM kullanıyorsanız, bu sayı Apache httpd'nin tüm yükünü kaldırabilecek kadar büyük olmalıdır. worker gibi çok çocuk süreçli bir MPM kullanıyorsanız, toplam evre sayısı Apache httpd'nin tüm yükünü kaldırabilecek kadar büyük olmalıdır.

ThreadsPerChild için öntanımlı değer mpm_winnt kullanıldığında 64 diğerleri için 25’tir.

ThreadStackSize Yönergesi

Açıklama: | İstemci bağlantılarını elde eden evreler tarafından kullanılan yığıtın bayt cinsinden uzunluğunu belirler.
Sözdizimi: | ThreadStackSize boyut
Öntanımlı: | NetWare üzerinde 65536; diğer işletim sistemlerinde değişir.
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | event, worker, mpm_winnt, mpm_netware, mpmt_os2
Uyumluluk: | Apache HTTP Sunucusu 2.1 ve sonrasında kullanılabilir.

ThreadStackSize yönergesi, istemci bağlantılarını elde eden evreler ve bu bağlantıları işlemekte yardımcı olan modül çağrıları tarafından kullanılan yığıtın bayt cinsinden uzunluğunu belirler. Çoğu durumda işletim sistemi yığıtı uygun bir boyuta ayarlar, fakat yine de ayarlanmasını gerektirecek bazı durumlar olabilir:

  • HP-UX gibi görece küçük yığıt boyuna sahip platformlarda, Apache httpd, görece büyük yığıt alanı kullanan bazı üçüncü parti modüller yüzünden çökebilir. Bu modüller öntanımlı yığıt boyu daha büyük olan diğer platformlarda sorunsuz çalışabilir. Bu tür çökmeler ThreadStackSize yönergesine daha büyük yığıt boyu atanarak çözümlenir. Böyle bir ayarlamayı sadece üçüncü parti modülün üreticisi bunun gerekliliğini belirtmişse veya Apache httpd’nin evre yığıt boyutunun küçüklüğünden dolayı çöktüğü teşhis edildiği takdirde yapınız.
  • Öntanımlı yığıt boyu Apache sunucusu için gerekenden belirgin şekilde büyük bazı platformalarda, eğer ThreadStackSize yönergesi ile bu boyuttan daha düşük bir değer atanmışsa çocuk süreç başına evre sayısının yüksek olduğu durumlarda bu yığıt yetmeyebilir. Böyle bir ayarlama sadece sunucunun öldüresiye denendiği dolayısıyla yığıt boyutlarının aşırı zorlandığı deneme ortamlarında yapılmalıdır. Gereken en küçük yığıt boyutu kullanılan modüle sıkı sıkıya bağlıdır, fakat Apache httpd yapılandırmasında yapılan bir değişiklik mevcut ThreadStackSize ayarını geçersiz hale getirebilir.
  • Linux üzerinde, ilgili sistem çağrısı en küçük yığıt boyutu olarak bu değeri kullanacağından, bu yönerge sadece öntanımlı yığıt boyutunu arttırmak için kullanılabilir. ulimit -s için (çoğunlukla büyükçe) soft sınır (sınırsızsa 8MB), öntanımlı yığıt boyutu olarak kullanılır.
Çocuk süreç başına yüksek bir evre sayısı gerekmedikçe ThreadStackSize değerinin azaltılmaması önerilir. Bazı platformlarda (Linux dahil), 128000 ayarı zaten çok düşüktür ve daha da azaltmak bazı modüllerle çökmeye sebep olur.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


event - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache MPM event

Description: | A variant of the worker MPM with the goal of consuming threads only for connections with active processing
Status: | MPM
Module Identifier: | mpm_event_module
Source File: | event.c

Summary

The event Multi-Processing Module (MPM) is designed to allow more requests to be served simultaneously by passing off some processing work to the listeners threads, freeing up the worker threads to serve new requests.

To use the event MPM, add --with-mpm=event to the configure script's arguments when building the httpd.

See also

  • The worker MPM

Relationship with the Worker MPM

event is based on the worker MPM, which implements a hybrid multi-process multi-threaded server. A single control process (the parent) is responsible for launching child processes. Each child process creates a fixed number of server threads as specified in the ThreadsPerChild directive, as well as a listener thread which listens for connections and passes them to a worker thread for processing when they arrive.

Run-time configuration directives are identical to those provided by worker, with the only addition of the AsyncRequestWorkerFactor.

How it Works

This MPM tries to fix the 'keep alive problem' in HTTP. After a client completes the first request, it can keep the connection open, sending further requests using the same socket and saving significant overhead in creating TCP connections. However, Apache HTTP Server traditionally keeps an entire child process/thread waiting for data from the client, which brings its own disadvantages. To solve this problem, this MPM uses a dedicated listener thread for each process to handle both the Listening sockets, all sockets that are in a Keep Alive state, sockets where the handler and protocol filters have done their work and the ones where the only remaining thing to do is send the data to the client.

The total amount of connections that a single process/threads block can handle is regulated by the AsyncRequestWorkerFactor directive.

Async connections

Async connections would need a fixed dedicated worker thread with the previous MPMs but not with event. The status page of mod_status shows new columns under the Async connections section:

Writing
While sending the response to the client, it might happen that the TCP write buffer fills up because the connection is too slow. Usually in this case a write() to the socket returns EWOULDBLOCK or EAGAIN, to become writable again after an idle time. The worker holding the socket might be able to offload the waiting task to the listener thread, that in turn will re-assign it to the first idle worker thread available once an event will be raised for the socket (for example, "the socket is now writable"). Please check the Limitations section for more information.
Keep-alive
Keep Alive handling is the most basic improvement from the worker MPM. Once a worker thread finishes to flush the response to the client, it can offload the socket handling to the listener thread, that in turns will wait for any event from the OS, like "the socket is readable". If any new request comes from the client, then the listener will forward it to the first worker thread available. Conversely, if the KeepAliveTimeout occurs then the socket will be closed by the listener. In this way the worker threads are not responsible for idle sockets and they can be re-used to serve other requests.
Closing
Sometimes the MPM needs to perform a lingering close, namely sending back an early error to the client while it is still transmitting data to httpd. Sending the response and then closing the connection immediately is not the correct thing to do since the client (still trying to send the rest of the request) would get a connection reset and could not read the httpd's response. So in such cases, httpd tries to read the rest of the request to allow the client to consume the response. The lingering close is time bounded but it can take relatively long time, so a worker thread can offload this work to the listener.

These improvements are valid for both HTTP/HTTPS connections.

Limitations

The improved connection handling may not work for certain connection filters that have declared themselves as incompatible with event. In these cases, this MPM will fall back to the behaviour of the worker MPM and reserve one worker thread per connection. All modules shipped with the server are compatible with the event MPM.

A similar restriction is currently present for requests involving an output filter that needs to read and/or modify the whole response body. If the connection to the client blocks while the filter is processing the data, and the amount of data produced by the filter is too big to be buffered in memory, the thread used for the request is not freed while httpd waits until the pending data is sent to the client.
To illustrate this point we can think about the following two situations: serving a static asset (like a CSS file) versus serving content retrieved from FCGI/CGI or a proxied server. The former is predictable, namely the event MPM has full visibility on the end of the content and it can use events: the worker thread serving the response content can flush the first bytes until EWOULDBLOCK or EAGAIN is returned, delegating the rest to the listener. This one in turn waits for an event on the socket, and delegates the work to flush the rest of the content to the first idle worker thread. Meanwhile in the latter example (FCGI/CGI/proxied content) the MPM can't predict the end of the response and a worker thread has to finish its work before returning the control to the listener. The only alternative is to buffer the response in memory, but it wouldn't be the safest option for the sake of the server's stability and memory footprint.

Background material

The event model was made possible by the introduction of new APIs into the supported operating systems:

  • epoll (Linux)
  • kqueue (BSD)
  • event ports (Solaris)

Before these new APIs where made available, the traditional select and poll APIs had to be used. Those APIs get slow if used to handle many connections or if the set of connections rate of change is high. The new APIs allow to monitor much more connections and they perform way better when the set of connections to monitor changes frequently. So these APIs made it possible to write the event MPM, that scales much better with the typical HTTP pattern of many idle connections.

The MPM assumes that the underlying apr_pollset implementation is reasonably threadsafe. This enables the MPM to avoid excessive high level locking, or having to wake up the listener thread in order to send it a keep-alive socket. This is currently only compatible with KQueue and EPoll.

Requirements

This MPM depends on APR's atomic compare-and-swap operations for thread synchronization. If you are compiling for an x86 target and you don't need to support 386s, or you are compiling for a SPARC and you don't need to run on pre-UltraSPARC chips, add --enable-nonportable-atomics=yes to the configure script's arguments. This will cause APR to implement atomic operations using efficient opcodes not available in older CPUs.

This MPM does not perform well on older platforms which lack good threading, but the requirement for EPoll or KQueue makes this moot.

  • To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended. However, it is possible to run this MPM on FreeBSD 5.2.1, if you use libkse (see man libmap.conf).
  • For NetBSD, at least version 2.0 is recommended.
  • For Linux, a 2.6 kernel is recommended. It is also necessary to ensure that your version of glibc has been compiled with support for EPoll.

AsyncRequestWorkerFactor Directive

Description: | Limit concurrent connections per process
Syntax: | AsyncRequestWorkerFactor factor
Default: | 2
Context: | server config
Status: | MPM
Module: | event
Compatibility: | Available in version 2.3.13 and later

The event MPM handles some connections in an asynchronous way, where request worker threads are only allocated for short periods of time as needed, and other connections with one request worker thread reserved per connection. This can lead to situations where all workers are tied up and no worker thread is available to handle new work on established async connections.

To mitigate this problem, the event MPM does two things:

  • it limits the number of connections accepted per process, depending on the number of idle request workers;
  • if all workers are busy, it will close connections in keep-alive state even if the keep-alive timeout has not expired. This allows the respective clients to reconnect to a different process which may still have worker threads available.

This directive can be used to fine-tune the per-process connection limit. A process will only accept new connections if the current number of connections (not counting connections in the "closing" state) is lower than:

ThreadsPerChild + (AsyncRequestWorkerFactor * number of idle workers)

An estimation of the maximum concurrent connections across all the processes given an average value of idle worker threads can be calculated with:

(ThreadsPerChild + (AsyncRequestWorkerFactor * number of idle workers)) * ServerLimit

Example

ThreadsPerChild = 10
ServerLimit = 4
AsyncRequestWorkerFactor = 2
MaxRequestWorkers = 40

idle_workers = 4 (average for all the processes to keep it simple)

max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * ServerLimit
                = (10 + (2 * 4)) * 4 = 72

When all the worker threads are idle, then absolute maximum numbers of concurrent connections can be calculared in a simpler way:

(AsyncRequestWorkerFactor + 1) * MaxRequestWorkers

Example

ThreadsPerChild = 10
ServerLimit = 4
MaxRequestWorkers = 40
AsyncRequestWorkerFactor = 2

If all the processes have all threads idle then:

idle_workers = 10

We can calculate the absolute maximum numbers of concurrent connections in two ways:

max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * ServerLimit
                = (10 + (2 * 10)) * 4 = 120

max_connections = (AsyncRequestWorkerFactor + 1) * MaxRequestWorkers
                = (2 + 1) * 40 = 120

Tuning AsyncRequestWorkerFactor requires knowledge about the traffic handled by httpd in each specific use case, so changing the default value requires extensive testing and data gathering from mod_status.

MaxRequestWorkers was called MaxClients prior to version 2.3.13. The above value shows that the old name did not accurately describe its meaning for the event MPM.

AsyncRequestWorkerFactor can take non-integer arguments, e.g "1.5".


mod_unixd - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_unixd

Açıklama: | Unix ailesi platformlar için temel (gerekli) güvenlik.
Durum: | Temel
Modül Betimleyici: | unixd_module
Kaynak Dosyası: | mod_unixd.c

Ayrıca bakınız:

  • suEXEC desteği

ChrootDir Yönergesi

Açıklama: | Sunucunun başlatıldıktan sonra chroot(8) yapacağı dizini belirler.
Sözdizimi: | ChrootDir /dizin/yolu
Öntanımlı: | none
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_unixd
Uyumluluk: | Apache HTTP Sunucusunun 2.2.10 and laterve sonraki sürümlerinde kullanılabilir.

Bu yönerge sunucuya başlatıldıktan sonra ağdan gelen istekleri kabul etmeden önce belirtilen dizine chroot(8) yapmasını söyler.

Sunucuyu chroot altında çalıştırmanın basit bir işlem olmadığına ve özellikle CGI veya PHP gibi betikler çalıştırıyorsanız ek ayarlamalar yapmanız gerektiğine dikkat ediniz. Lütfen, bu özelliği kullanmaya çalışmadan önce chroot işlemleri hakkında gerektiği kadar bilgi sahibi olduğunuzdan emin olunuz.

Group Yönergesi

Açıklama: | İsteklere yanıt verecek sunucunun ait olacağı grubu belirler.
Sözdizimi: | Group unix-grubu
Öntanımlı: | Group #-1
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_unixd

Group yönergesi, sunucunun hangi grup altında isteklere yanıt vereceğini belirler. Bu yönergenin uygulanabilmesi için sunucunun root olarak çalıştırılmış olması gerekir. Sunucuyu root dışında bir kullanıcı başlattığı takdirde, sunucu belirtilen gruba geçemez ve kullanıcının kendi grubunda çalışmaya devam eder. unix-grubu şunlardan biri olabilir:

Bir grup adı
Gruba ismiyle başvurulur.
# ardından grup numarası
Gruba numarası ile başvurulur.
Group www-group

Çalışan sunucu için özellikle yeni bir grup atamanız önerilir. Bazı sistem yöneticileri nobody grubunu kullanırlar fakat bu her zaman mümkün olmadığı gibi arzulanan da değildir.

Güvenlik

Ne yaptığınızı ve ne tehlikelere yol açacağınızı bilmiyorsanız Group (veya User) yönergesine değer olarak root atamayınız.

Ayrıca bakınız:

  • VHostUser
  • SuexecUserGroup

Suexec Yönergesi

Açıklama: | suEXEC özelliğini etkin veya etkisiz yapar
Sözdizimi: | Suexec On|Off
Öntanımlı: | suexec çalıştırılabiliri uygun sahip ve kip ile mevcutsa On, değilse Off
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_unixd

On olduğunda, suexec çalıştırılabiliri yoksa veya dosya kipi ve sahibi geçersizse httpd başlatılamaz.

Off olduğunda, suexec çalıştırılabiliri varsa ve hatta dosya kipi ve sahibi geçerli olsa bile suEXEC özelliği iptal edilir.

User Yönergesi

Açıklama: | İsteklere yanıt verecek sunucunun ait olacağı kullanıcıyı belirler.
Sözdizimi: | User unix-kullanıcısı
Öntanımlı: | User #-1
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_unixd

User yönergesi, sunucunun hangi kullanıcı olarak isteklere yanıt vereceğini belirler. Bu yönergenin uygulanabilmesi için sunucunun root olarak çalıştırılmış olması gerekir. Sunucuyu root dışında bir kullanıcı başlattığı takdirde, sunucu belirtilen kullanıcıya geçemez ve mevcut kullanıcıyla çalışmaya devam eder. Eğer sunucuyu root olarak başlatmışsanız ana süreç root olarak çalışmaya devam edecektir. unix-kullanıcısı şunlardan biri olabilir:

Bir kullanıcı adı
Gruba ismiyle başvurulur.
# ardından kullanıcı numarası
Kullanıcıya numarası ile başvurulur.

Bu yönergede belirtilecek kullanıcının, başkaları tarafından üzerinde değişiklik yapılabilecek dosyalardan başkasına erişemeyen bir kullanıcı olmaması gerektiği gibi, HTTP isteklerini işlemek dışında işlemler de yapabilen bir kullanıcı olmamalıdır. Çalışan sunucu için özellikle yeni bir grup atamanız önerilir. Bazı sistem yöneticileri nobody kullanıcısını kullanırlar fakat nobody kullanıcısı sistemde başka amaçlarla kullanılabildiğinden bu her zaman mümkün olmadığı gibi arzulanan da değildir.

Güvenlik

Ne yaptığınızı ve ne tehlikelere yol açacağınızı bilmiyorsanız User (veya Group) yönergesine değer olarak root atamayınız.

Ayrıca bakınız:

  • VHostUser
  • SuexecUserGroup

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mpm_netware - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache MPM netware

Description: | Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
Status: | MPM
Module Identifier: | mpm_netware_module
Source File: | mpm_netware.c

Summary

This Multi-Processing Module (MPM) implements an exclusively threaded web server that has been optimized for Novell NetWare.

The main thread is responsible for launching child worker threads which listen for connections and serve them when they arrive. Apache HTTP Server always tries to maintain several spare 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.

The StartThreads, MinSpareThreads, MaxSpareThreads, and MaxThreads regulate how the main thread creates worker threads to serve requests. In general, Apache httpd is very self-regulating, so most sites do not need to adjust these directives from their default values. Sites with limited memory may need to decrease MaxThreads to keep the server from thrashing (spawning and terminating idle threads). More information about tuning process creation is provided in the performance hints documentation.

MaxConnectionsPerChild 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.

See also

  • Setting which addresses and ports Apache httpd uses

MaxThreads Directive

Description: | Set the maximum number of worker threads
Syntax: | MaxThreads number
Default: | MaxThreads 2048
Context: | server config
Status: | MPM
Module: | mpm_netware

The MaxThreads directive sets the desired maximum number worker threads allowable. The default value is also the compiled in hard limit. Therefore it can only be lowered, for example:

MaxThreads 512

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mpmt_os2 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache MPM os2

Description: | Hybrid multi-process, multi-threaded MPM for OS/2
Status: | MPM
Module Identifier: | mpm_mpmt_os2_module
Source File: | mpmt_os2.c

Summary

The Server consists of a main, parent process and a small, static number of child processes.

The parent process' job is to manage the child processes. This involves spawning children as required to ensure there are always StartServers processes accepting connections.

Each child process consists of a pool of worker threads and a main thread that accepts connections and passes them to the workers via a work queue. The worker thread pool is dynamic, managed by a maintenance thread so that the number of idle threads is kept between MinSpareThreads and MaxSpareThreads.

See also

  • Setting which addresses and ports Apache uses


prefork - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache MPM prefork

Açıklama: | Evresiz ön çatallamalı HTTP sunucusu oluşturur
Durum: | MPM
Modül Betimleyici: | mpm_prefork_module
Kaynak Dosyası: | prefork.c

Özet

Bu çok süreçlilik modülü (MPM) evresiz ve çocuk süreçlerin önceden çatallandığı bir HTTP sunucusu oluşturur. Her çocuk süreç gelen bir isteğe yanıt verirken ebeveyn süreç çocuk süreç havuzunu yönetir. Evresiz kütüphanelerle uyumluluk için evrelemeden kaçınma ihtiyacında olan siteler için uygundur. Ayrıca istekleri birbirlerinden yalıtmak için en iyi MPM’dir, dolayısıyla herhangi bir istekle ilgili bir sorun diğerlerini etkilemez.

Bu MPM kendi kendine her duruma çok iyi uyum sağladığından yapılandırma yönergeleri ile yapılandırılmaya nadiren ihtiyaç gösterir. Yönergelerin en önemlisi MaxRequestWorkers olup, değeri aynı anda almayı umduğunuz istek sayısını işleyebilecek kadar büyük, fiziksel belleğin tüm süreçlerin ihtiyaçlarını karşılamasına yetecek kadar da küçük olması gerekir.

Ayrıca bakınız:

  • Apache HTTP Sunucusunun kullandığı adres ve portların ayarlanması

Nasıl çalışır?

Bağlantıları dinleyip gerektiğinde onlara hizmet sunan çocuk süreçleri devreye almak tek bir denetim sürecinin sorumluluğundadır. Apache httpd daima, gelen isteklere hizmet vermeye hazır bekleyen en fazla sayıda sunucu sürecini yedekte tutmaya veya boşta bekletmeye çalışır. Bu suretle, istemcilere isteklerinin sunulması için yeni çocuk süreçlerin çatallanmasını beklemek gerekmez.

Ana sürecin istekleri sunacak çocuk süreçleri oluşturma işlemini nasıl gerçekleştireceği StartServers, MinSpareServers, MaxSpareServers ve MaxRequestWorkers yönergeleri ile düzenlenir. Apache httpd kendiliğinden her duruma çok iyi uyum sağladığından, genelde, çoğu sitenin bu yönergelerin öntanımlı değerlerini değiştirmesi gerekmez. Aynı anda 256’dan fazla isteğe hizmet sunacak sitelerin MaxRequestWorkers değerini arttırmaları gerekebilir. Ancak, fiziksel belleği yeterli olmayan sitelerin de sunucunun belleği diske takaslamasını önlemek için bu değeri azaltmaları gerekebilir. Süreç oluşturmanın ayarlanması ile ilgili daha fazla bilgi edinmek için başarım arttırma ipuçları belgesine bakınız.

Unix altında 80. portu dinleyebilmek için ana sürecin root tarafından çalıştırılmış olması gerekirse de çocuk süreçler Apache httpd tarafından daha az yetkili bir kullanıcının aidiyetinde çalıştırılırlar. Apache httpd’nin çocuk süreçlerinin kullanıcı ve gruplarını ayarlamak için User ve Group yönergeleri kullanılır. Çocuk süreçlerin sunacakları içeriği okumaya yetkili olmaları gerekir, fakat bu yetkinin mümkün olduğunca kısıtlı tutulmasına çalışılmalıdır.

MaxConnectionsPerChild yönergesi ana sunucunun eski süreçleri öldürüp yenilerini oluşturmayı ne kadar sıklıkla yapacağını denetler.

Bu MPM, gürleyen sürü sorunu ortaya çıktığında (genelde çok sayıda dinlenen soket varlığında) gelen bağlantılara erişimi dizgileştirmek için mpm-accept muteksini kullanır. Bu muteksin gerçeklenimle ilgili hususları Mutex yönergesi ile yapılandırılabilir. Bu muteks hakkında ek bilgi için başarımın arttırılması belgesine bakınız.

MaxSpareServers Yönergesi

Açıklama: | Boştaki çocuk süreçlerin azami sayısı
Sözdizimi: | MaxSpareServers sayı
Öntanımlı: | MaxSpareServers 10
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | prefork

MaxSpareServers yönergesi boştaki çocuk sunucu süreçlerinin azami sayısını belirler. Boştaki süreç, o an bir isteğe hizmet sunmayan süreçtir. Eğer MaxSpareServers sayıda süreçten daha fazla boşta süreç varsa ana süreç bu fazlalıkları öldürecektir.

Bu parametrenin ayarlanması sadece çok meşgul siteler için gerekli olabilir. Bu parametreye çok büyük bir değerin atanması oldukça kötü bir fikirdir. Eğer bu değeri MinSpareServers değerine eşit veya daha küçük bir değere ayarlarsanız, Apache HTTP Sunucusu bu değeri kendiliğinden MinSpareServers + 1 olarak değiştirecektir.

Ayrıca bakınız:

  • MinSpareServers
  • StartServers
  • MaxSpareThreads

MinSpareServers Yönergesi

Açıklama: | Boştaki çocuk süreçlerin asgari sayısı
Sözdizimi: | MinSpareServers sayı
Öntanımlı: | MinSpareServers 5
Bağlam: | sunucu geneli
Durum: | MPM
Modül: | prefork

MinSpareServers yönergesi boştaki çocuk sunucu süreçlerinin asgari sayısını belirler. Boştaki süreç, o an bir isteğe hizmet sunmayan süreçtir. Eğer MinSpareServers sayıda süreçten daha az boşta süreç varsa ana süreç sayıyı tamamlamak için yeni çocuk süreçler oluşturacaktır: Bir tane oluşturur, 1 saniye bekler, sonra 2 tane oluşturur, 1 saniye bekler, sonra 4 tane oluşturur ve saniyede 32 çocuk süreç oluşturuluncaya kadar böyle üstel olarak artar. Artış MinSpareServers ile belirlenen sayıda duracaktır.

Bu parametrenin ayarlanması sadece çok meşgul siteler için gerekli olabilir. Bu parametreye çok büyük bir değerin atanması oldukça kötü bir fikirdir.

Ayrıca bakınız:

  • MaxSpareServers
  • StartServers
  • MinSpareThreads

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mpm_winnt - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache MPM winnt

Description: | Multi-Processing Module optimized for Windows NT.
Status: | MPM
Module Identifier: | mpm_winnt_module
Source File: | mpm_winnt.c

Summary

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

Capacity is configured using the ThreadsPerChild directive, which sets the maximum number of concurrent client connections.

By default, this MPM uses advanced Windows APIs for accepting new client connections. In some configurations, third-party products may interfere with this implementation, with the following messages written to the web server log:

Child: Encountered too many AcceptEx faults accepting client connections.
winnt_mpm: falling back to 'AcceptFilter none'.

The MPM falls back to a safer implementation, but some client requests were not processed correctly. In order to avoid this error, use AcceptFilter with accept filter none.

AcceptFilter http none
AcceptFilter https none

In Apache httpd 2.0 and 2.2, Win32DisableAcceptEx was used for this purpose.

The WinNT MPM differs from the Unix MPMs such as worker and event in several areas:

  • When a child process is exiting due to shutdown, restart, or MaxConnectionsPerChild, active requests in the exiting process have TimeOut seconds to finish before processing is aborted. Alternate types of restart and shutdown are not implemented.
  • New child processes read the configuration files instead of inheriting the configuration from the parent. The behavior will be the same as on Unix if the child process is created at startup or restart, but if a child process is created because the prior one crashed or reached MaxConnectionsPerChild, any pending changes to the configuration will become active in the child at that point, and the parent and child will be using a different configuration. If planned configuration changes have been partially implemented and the current configuration cannot be parsed, the replacement child process cannot start up and the server will halt. Because of this behavior, configuration files should not be changed until the time of a server restart.
  • The monitor and fatal_exception hooks are not currently implemented.
  • AcceptFilter is implemented in the MPM and has a different type of control over handling of new connections. (Refer to the AcceptFilter documentation for details.)

See also

  • Using Apache HTTP Server on Microsoft Windows


worker - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache MPM worker

Açıklama: | Çok evreli ve çok süreçli melez bir HTTP sunucusu oluşturan çok süreçlilik modülü.
Durum: | MPM
Modül Betimleyici: | mpm_worker_module
Kaynak Dosyası: | worker.c

Özet

Bu çok süreçlilik modülü (MPM) hem çok süreçli hem de çok evreli olabilen melez bir sunucu oluşturur. İstekleri sunmak için evreleri kullanması sebebiyle çok süreçli bir sunucudan daha az sistem kaynağı harcayarak daha çok isteğe hizmet sunabilir. Bununla birlikte, herbiri çok sayıda evreye sahip çok sayıda süreci canlı tutarak bir çok süreçli sunucu kadar kararlı olur.

Bu MPM’i denetim altında tutmakta kullanılan en önemli yönergeler, her çocuk süreç için konuşlandırılacak evre sayısını belirleyen ThreadsPerChild yönergesi ile devreye sokulacak toplam evre sayısının azamisini belirleyen MaxRequestWorkers yönergesidir.

Ayrıca bakınız:

  • Apache HTTP Sunucusunun kullandığı adres ve portların ayarlanması

Nasıl çalışır?

Çocuk süreçleri devreye almaktan tek bir süreç (ana süreç) sorumludur. Her çocuk süreç ThreadsPerChild yönergesinde belirtilen sayıda evre konuşlandırır. Bunlardan ayrı olarak, bir dinleyici evre bağlantıları dinleyip gelenleri işlenmek üzere bu sunucu evrelerinden birine aktarır.

Apache HTTP Sunucusu daima, gelen isteklere hizmet sunmaya hazır yedek veya boştaki sunucu evrelerinden oluşan bir havuzu canlı tutmaya çalışır. Bu suretle, istemcilere isteklerinin sunulması için yeni çocuk süreçlerin çatallanmasını, dolayısıyla yeni evrelerin konuşlandırılmasını beklemek gerekmez. Başlangıçta çalıştırılacak çocuk süreçlerin sayısı StartServers yönergesinde belirtilir. Apache httpd, çalışma süresi boyunca MinSpareThreads ve MaxSpareThreads yönergeleri ile belirtilen sınırlar dahilinde kalmak üzere gerektiğinde süreçleri öldürerek gerektiğinde yenilerini devreye alarak tüm süreçlerdeki toplam evre sayısını sabit tutmaya çalışır. Bu işlem kendiliğinden çok iyi yürüdüğünden bu yönergelere öntanımlı değerlerinden farklı değerlerin atanması nadiren gerekli olur. Aynı anda hizmet sunulabilecek istemcilerin sayısı (yani, tüm süreçlerin toplam evre sayısı) MaxRequestWorkers yönergesi ile belirlenir. Etkin çocuk süreçlerin sayısı ise MaxRequestWorkers yönergesindeki değerin ThreadsPerChild yönergesindeki değere bölünmesi ile elde edilir.

Bu iki yönerge aynı anda etkin olabilecek çocuk süreçlerin ve her çocuk süreçteki sunucu evreleri sayısının üst sınırını belirler ve bu sınır sadece ana sunucu tamamen durdurulup yeniden başlatılarak değiştirilebilir. ServerLimit yönergesinin değeri etkin çocuk süreç sayısının üst sınırı olup MaxRequestWorkers yönergesindeki değerin ThreadsPerChild yönergesindeki değere bölünmesi ile elde değere eşit veya bundan küçük olması gerekir. ThreadLimit yönergesinin değeri ise sunucu evreleri sayısının üst sınırını belirler ve ThreadsPerChild yönergesindeki değerden büyük veya ona eşit olması gerekir.

Sonlandırma sırasında etkin çocuk süreçlere ek olarak mevcut istemci bağlantılarını işleme sokmaya çalışan tek bir sunucu evresinden başka fazladan bir çocuk süreç etkin kalabileceği gibi sonlandırılacak süreç sayısının en fazla MaxRequestWorkers olması gerekirse de gerçekte sayı bundan küçük olabilir. Şöyle bir işlemle tek bir çocuk sürecin sonlandırılması iptal edilerek bu gibi durumlara karşı önlem alınabilir:

  • MaxConnectionsPerChild yönergesinin değeri sıfır yapılır.
  • MaxSpareThreads ve MaxRequestWorkers yönergelerinin değerleri birbirine eşitlenir.

worker modülünün öntanımlı süreç-evre yapılandırması genelde şöyledir:

ServerLimit         16
StartServers         2
MaxRequestWorkers  150
MinSpareThreads     25
MaxSpareThreads     75
ThreadsPerChild     25

Unix altında 80. portu dinleyebilmek için ana sürecin root tarafından çalıştırılmış olması gerekirse de çocuk süreçler ve evreler Apache httpd tarafından daha az yetkili bir kullanıcının aidiyetinde çalıştırılırlar. Apache httpd’nin çocuk süreçlerinin kullanıcı ve gruplarını ayarlamak için User ve Group yönergeleri kullanılır. Çocuk süreçlerin sunacakları içeriği okumaya yetkili olmaları gerekir, fakat bu yetkinin mümkün olduğunca kısıtlı tutulmasına çalışılmalıdır. Bundan başka, suexec kullanılmadığı takdirde, bu yönergeler CGI betikleri tarafından miras alınacak yetkili kullanıcı ve grubu da ayarlarlar.

MaxConnectionsPerChild yönergesi ana sunucunun eski süreçleri öldürüp yenilerini oluşturmayı ne kadar sıklıkla yapacağını denetler.

Bu MPM, gürleyen sürü sorunu ortaya çıktığında (genelde çok sayıda dinlenen soket varlığında) gelen bağlantılara erişimi dizgileştirmek için mpm-accept muteksini kullanır. Bu muteksin gerçeklenimle ilgili hususları Mutex yönergesi ile yapılandırılabilir. Bu muteks hakkında ek bilgi için başarımın arttırılması belgesine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_access_compat - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_access_compat

Description: | Group authorizations based on host (name or IP address)
Status: | Extension
Module Identifier: | access_compat_module
Source File: | mod_access_compat.c
Compatibility: | Available in Apache HTTP Server 2.3 as a compatibility module with previous versions of Apache httpd 2.x. The directives provided by this module have been deprecated by the new authz refactoring. Please see mod_authz_host

Summary

The directives provided by mod_access_compat are used in <Directory>, <Files>, and <Location> sections as well as .htaccess files to control access to particular parts of the server. Access can be controlled based on the client hostname, IP address, or other characteristics of the client request, as captured in environment variables. The Allow and Deny directives are used to specify which clients are or are not allowed access to the server, while the Order directive sets the default access state, and configures how the Allow and Deny directives interact with each other.

Both host-based access restrictions and password-based authentication may be implemented simultaneously. In that case, the Satisfy directive is used to determine how the two sets of restrictions interact.

Note

The directives provided by mod_access_compat have been deprecated by the new authz refactoring. Please see mod_authz_host.

In general, access restriction directives apply to all access methods (GET, PUT, POST, etc). This is the desired behavior in most cases. However, it is possible to restrict some methods, while leaving other methods unrestricted, by enclosing the directives in a <Limit> section.

Merging of configuration sections

When any directive provided by this module is used in a new configuration section, no directives provided by this module are inherited from previous configuration sections.

See also

  • Require
  • mod_authz_host
  • mod_authz_core

Allow Directive

Description: | Controls which hosts can access an area of the server
Syntax: | Allow from all|host|env=[!]env-variable [host|env=[!]env-variable] ...
Context: | directory, .htaccess
Override: | Limit
Status: | Extension
Module: | mod_access_compat

The Allow directive affects which hosts can access an area of the server. Access can be controlled by hostname, IP address, IP address range, or by other characteristics of the client request captured in environment variables.

The first argument to this directive is always from. The subsequent arguments can take three different forms. If Allow from all is specified, then all hosts are allowed access, subject to the configuration of the Deny and Order directives as discussed below. To allow only particular hosts or groups of hosts to access the server, the host can be specified in any of the following formats:

A (partial) domain-name
Allow from example.org
Allow from .net example.edu

Hosts whose names match, or end in, this string are allowed access. Only complete components are matched, so the above example will match foo.example.org but it will not match fooexample.org. This configuration will cause Apache httpd to perform a double DNS lookup on the client IP address, regardless of the setting of the HostnameLookups directive. It will do a reverse DNS lookup on the IP address to find the associated hostname, and then do a forward lookup on the hostname to assure that it matches the original IP address. Only if the forward and reverse DNS are consistent and the hostname matches will access be allowed.

A full IP address
Allow from 10.1.2.3
Allow from 192.168.1.104 192.168.1.205

An IP address of a host allowed access

A partial IP address
Allow from 10.1
Allow from 10 172.20 192.168.2

The first 1 to 3 bytes of an IP address, for subnet restriction.

A network/netmask pair
Allow from 10.1.0.0/255.255.0.0

A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction.

A network/nnn CIDR specification
Allow from 10.1.0.0/16

Similar to the previous case, except the netmask consists of nnn high-order 1 bits.

Note that the last three examples above match exactly the same set of hosts.

IPv6 addresses and IPv6 subnets can be specified as shown below:

Allow from 2001:db8::a00:20ff:fea7:ccea
Allow from 2001:db8::a00:20ff:fea7:ccea/10

The third format of the arguments to the Allow directive allows access to the server to be controlled based on the existence of an environment variable. When Allow from env=env-variable is specified, then the request is allowed access if the environment variable env-variable exists. When Allow from env=!env-variable is specified, then the request is allowed access if the environment variable env-variable doesn't exist. The server provides the ability to set environment variables in a flexible way based on characteristics of the client request using the directives provided by mod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clients User-Agent (browser type), Referer, or other HTTP request header fields.

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory "/docroot">
    Order Deny,Allow
    Deny from all
    Allow from env=let_me_in
</Directory>

In this case, browsers with a user-agent string beginning with KnockKnock/2.0 will be allowed access, and all others will be denied.

Merging of configuration sections

When any directive provided by this module is used in a new configuration section, no directives provided by this module are inherited from previous configuration sections.

Deny Directive

Description: | Controls which hosts are denied access to the server
Syntax: | Deny from all|host|env=[!]env-variable [host|env=[!]env-variable] ...
Context: | directory, .htaccess
Override: | Limit
Status: | Extension
Module: | mod_access_compat

This directive allows access to the server to be restricted based on hostname, IP address, or environment variables. The arguments for the Deny directive are identical to the arguments for the Allow directive.

Order Directive

Description: | Controls the default access state and the order in which Allow and Deny are evaluated.
Syntax: | Order ordering
Default: | Order Deny,Allow
Context: | directory, .htaccess
Override: | Limit
Status: | Extension
Module: | mod_access_compat

The Order directive, along with the Allow and Deny directives, controls a three-pass access control system. The first pass processes either all Allow or all Deny directives, as specified by the Order directive. The second pass parses the rest of the directives (Deny or Allow). The third pass applies to all requests which do not match either of the first two.

Note that all Allow and Deny directives are processed, unlike a typical firewall, where only the first match is used. The last match is effective (also unlike a typical firewall). Additionally, the order in which lines appear in the configuration files is not significant -- all Allow lines are processed as one group, all Deny lines are considered as another, and the default state is considered by itself.

Ordering is one of:

Allow,Deny
First, all Allow directives are evaluated; at least one must match, or the request is rejected. Next, all Deny directives are evaluated. If any matches, the request is rejected. Last, any requests which do not match an Allow or a Deny directive are denied by default.
Deny,Allow
First, all Deny directives are evaluated; if any match, the request is denied unless it also matches an Allow directive. Any requests which do not match any Allow or Deny directives are permitted.
Mutual-failure
This order has the same effect as Order Allow,Deny and is deprecated in its favor.

Keywords may only be separated by a comma; no whitespace is allowed between them.

Match | Allow,Deny result | Deny,Allow result
Match Allow only | Request allowed | Request allowed
Match Deny only | Request denied | Request denied
No match | Default to second directive: Denied | Default to second directive: Allowed
Match both Allow & Deny | Final match controls: Denied | Final match controls: Allowed

In the following example, all hosts in the example.org domain are allowed access; all other hosts are denied access.

Order Deny,Allow
Deny from all
Allow from example.org

In the next example, all hosts in the example.org domain are allowed access, except for the hosts which are in the foo.example.org subdomain, who are denied access. All hosts not in the example.org domain are denied access because the default state is to Deny access to the server.

Order Allow,Deny
Allow from example.org
Deny from foo.example.org

On the other hand, if the Order in the last example is changed to Deny,Allow, all hosts will be allowed access. This happens because, regardless of the actual ordering of the directives in the configuration file, the Allow from example.org will be evaluated last and will override the Deny from foo.example.org. All hosts not in the example.org domain will also be allowed access because the default state is Allow.

The presence of an Order directive can affect access to a part of the server even in the absence of accompanying Allow and Deny directives because of its effect on the default access state. For example,

<Directory "/www">
    Order Allow,Deny
</Directory>

will Deny all access to the /www directory because the default access state is set to Deny.

The Order directive controls the order of access directive processing only within each phase of the server's configuration processing. This implies, for example, that an Allow or Deny directive occurring in a <Location> section will always be evaluated after an Allow or Deny directive occurring in a <Directory> section or .htaccess file, regardless of the setting of the Order directive. For details on the merging of configuration sections, see the documentation on How Directory, Location and Files sections work.

Merging of configuration sections

When any directive provided by this module is used in a new configuration section, no directives provided by this module are inherited from previous configuration sections.

Satisfy Directive

Description: | Interaction between host-level access control and user authentication
Syntax: | Satisfy Any|All
Default: | Satisfy All
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_access_compat
Compatibility: | Influenced by <Limit> and <LimitExcept> in version 2.0.51 and later

Access policy if both Allow and Require used. The parameter can be either All or Any. This directive is only useful if access to a particular area is being restricted by both username/password and client host address. In this case the default behavior (All) is to require that the client passes the address access restriction and 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.

For example, if you wanted to let people on your network have unrestricted access to a portion of your website, but require that people outside of your network provide a password, you could use a configuration similar to the following:

Require valid-user
Allow from 192.168.1
Satisfy Any

Another frequent use of the Satisfy directive is to relax access restrictions for a subdirectory:

<Directory "/var/www/private">
    Require valid-user
</Directory>

<Directory "/var/www/private/public">
    Allow from all
    Satisfy Any
</Directory>

In the above example, authentication will be required for the /var/www/private directory, but will not be required for the /var/www/private/public directory.

Since version 2.0.51 Satisfy directives can be restricted to particular methods by <Limit> and <LimitExcept> sections.

Merging of configuration sections

When any directive provided by this module is used in a new configuration section, no directives provided by this module are inherited from previous configuration sections.

See also

  • Allow
  • Require


mod_actions - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_actions

Description: | Execute CGI scripts based on media type or request method.
Status: | Base
Module Identifier: | actions_module
Source File: | mod_actions.c

Summary

This module has two directives. The Action directive lets you run CGI scripts whenever a file of a certain MIME content type is requested. The Script 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.

See also

  • mod_cgi
  • Dynamic Content with CGI
  • Apache httpd's Handler Use

Action Directive

Description: | Activates a CGI script for a particular handler or content-type
Syntax: | Action action-type cgi-script [virtual]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_actions
Compatibility: | The virtual modifier and handler passing were introduced in Apache 2.1

This directive adds an action, which will activate cgi-script when action-type is triggered by the request. The cgi-script is the URL-path to a resource that has been designated as a CGI script using ScriptAlias or AddHandler. The action-type can be either a handler 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. The handler used for the particular request is passed using the REDIRECT_HANDLER variable.

Example: MIME type

# Requests for files of a particular MIME content type:
Action image/gif /cgi-bin/images.cgi

In this example, requests for files with a MIME content type of image/gif will be handled by the specified cgi script /cgi-bin/images.cgi.

Example: File extension

# Files of a particular file extension
AddHandler my-file-type .xyz
Action my-file-type "/cgi-bin/program.cgi"

In this example, requests for files with a file extension of .xyz are handled by the specified cgi script /cgi-bin/program.cgi.

The optional virtual modifier turns off the check whether the requested file really exists. This is useful, for example, if you want to use the Action directive in virtual locations.

<Location "/news">
    SetHandler news-handler
    Action news-handler "/cgi-bin/news.cgi" virtual
</Location>

See also

  • AddHandler

Script Directive

Description: | Activates a CGI script for a particular request method.
Syntax: | Script method cgi-script
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_actions

This directive adds an action, which will activate cgi-script when a file is requested using the method of method. The cgi-script is the URL-path to a resource that has been designated as a CGI script using ScriptAlias or AddHandler. The URL and file path of the requested document is sent using the standard CGI PATH_INFO and PATH_TRANSLATED environment variables.

Any arbitrary method name may be used. Method names are case-sensitive, so Script PUT and Script put have two entirely different effects.

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 GET will only be called if there are query arguments present (e.g., foo.html?hi). Otherwise, the request will proceed normally.

# All GET requests go here
Script GET "/cgi-bin/search"

# A CGI PUT handler
Script PUT "/~bob/put.cgi"

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_alias - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_alias

Açıklama: | Belge ağacının parçalarının dosya sisteminin parçalarıyla eşlenmesini sağlar ve URL yönlendirmesi yapar.
Durum: | Temel
Modül Betimleyici: | alias_module
Kaynak Dosyası: | mod_alias.c

Özet

Bu modülde bulunan yönergeler sunucuya istek olarak gelen URL’lerin denetlenmesini ve değiştirilmesini mümkün kılar. Alias ve ScriptAlias yönergeleri URL’lerin dosya sisteminin dizinlerine eşlenmesini sağlar. Böylece, kök dizini DocumentRoot ile belirtilen site belge ağacı altında bulunmayan içeriğe erişmek mümkün olur. ScriptAlias yönergesi buna ek olarak hedef dizini sadece CGI betiklerini içeren dizin olarak imler.

Redirect yönergesi, farklı bir URL ile yeni bir istek yapmaları için istemcileri yönlendirmekte kullanılır. Çoğunlukla özkaynak başka bir yere taşındığında kullanılır.

Alias, ScriptAlias ve Redirect yönergeleri <Location> veya <LocationMatch> bölümleri içinde kullanıldığında hedef yolu veya URL'yi betimlemek için ifade sözdizimi kullanılabilir.

mod_alias modülü basit URL değiştirme görevlerini yerine getirmek için tasarlanmıştır. Sorgu dizgelerini işleme sokmak gibi daha karmaşık görevler için mod_rewrite modülü ile sağlanan araçlar kullanılır.

Ayrıca bakınız:

  • mod_rewrite
  • URL’lerin Dosya sistemi ile Eşlenmesi

İşlem Sırası

Farklı bağlamlarda bulunan Alias ve Redirect yönergeleri standart katıştırma kuralları ile ilgili diğer yönergeler gibi işleme sokulur. Fakat aynı bağlam dahilinde (örneğin, aynı <VirtualHost> bölümünde) çok fazla Alias ve Redirect varsa bunlar belli bir sıraya göre işleme sokulurlar.

İlk adımda, Alias’lardan önce bütün Redirect yönergeleri işleme sokulur. Bu bakımdan bir Redirect veya RedirectMatch ile eşleşen bir istek için hiçbir Alias uygulanmayacaktır. İkinci adımda yapılandırma dosyasında yer aldıkları sıraya göre Redirect ve Alias yönergeleri işleme sokulurlar, dolayısıyla ilk eşleşme öncelikli olmuş olur.

İlk eşleşmenin öncelikli olması sebebiyle, bu yönergelerin birden fazlası aynı alt yola uygulandığı takdirde, tüm yönergelerin etkili olabilmesi için en uzun yolu sıralamada en öne almalısınız. Örneğin aşağıdaki yapılandırma beklendiği gibi çalışacaktır:

Alias "/foo/bar" "/baz"
Alias "/foo" "/gaq"

Ama yukarıdaki iki satır ters sırada yerleştirilmiş olsaydı, /foo rumuzu daima /foo/bar rumuzundan önce eşleşecek, dolayısıyla ikinci yönerge yok sayılacaktı.

Alias, ScriptAlias ve Redirect yönergeleri <Location> veya <LocationMatch> bölümleri içinde kullanıldığında bu yönergeler küresel olarak tanımlı Alias, ScriptAlias ve Redirect yönergelerinden öncelikli olur.

Alias Yönergesi

Açıklama: | URL’leri dosya sistemi konumlarıyla eşler.
Sözdizimi: | Alias [URL-yolu] dosya-yolu | dizin-yolu
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Temel
Modül: | mod_alias

Alias yönergesi, belgelerin DocumentRoot dizininden farklı bir yerde saklanmasını mümkün kılar. URL-yolu ile başlayan URL’ler (% imlemesi çözüldükten sonra) dizin-yolu ile başlayan yerel dosyalarla eşlenir. URL-yolu, harf büyüklüğüne duyarsız sistemlerde bile harf büyüklüğüne duyarlıdır.

Alias "/image" "/ftp/pub/image"

http://example.com/image/foo.gif şeklinde bir istek, sunucunun /ftp/pub/image/foo.gif dosyasıyla yanıt vermesine sebep olurdu. Sadece tam yol parçaları eşleştirilir; bu bakımdan yukarıdaki Alias yapılandırması http://example.com/imagefoo.gif ile eşleşmez. Düzenli ifadelerin kullanıldığı daha karmaşık eşleşmeler için AliasMatch yönergesine bakınız.

URL-yolu’nu bir / ile sonlandırırsanız Alias yönergesini yorumlarken sunucunun da sona bir / ekleyeceğine dikkat ediniz. Yani, eğer

Alias "/icons/" "/usr/local/apache/icons/"

diye bir tanım yaparsanız sona bir / ekleme ihtiyacından dolayı /icons URL’si için bir Alias kullanılmayacaktır.

Alias hedefleri için ek <Directory> bölümleri belirtmeniz gerekebileceğine dikkat ediniz. <Directory> bölümlerinden önce yer alan Alias yönergelerine özellikle bakılır, dolayısıyla sadece Alias hedefleri etkilenir. (Bununla birlikte, Alias yönergelerinden önce işleme sokulan <Location> bölümlerinin uygulanacağına dikkat ediniz.)

Özellikle, DocumentRoot dışında bir dizine bir Alias oluşturuyorsanız hedef dizine doğrudan erişim izni vermeniz gerekebilir.

Alias "/image" "/ftp/pub/image"
<Directory "/ftp/pub/image">
    Require all granted
</Directory>

URL-yolu değiştirgesindeki bölü çizgilerinin sayısı istek URL-yolundakiler kadardır.

Eğer Alias yönergesi <Location> veya <LocationMatch> bölümleri içinde kullanılırsa URL-yolu yoksayılır ve dosya-yolu ifade sözdizimi kullanılarak yorumlanır.
Bu sözdizimi Apache 2.4.19 ve sonrasında kulanılabilir.

<Location "/image">
    Alias "/ftp/pub/image"
</Location>
<LocationMatch "/error/(?<NUMBER>[0-9]+)">
    Alias "/usr/local/apache/errors/%{env:MATCH_NUMBER}.html"
</LocationMatch>

AliasMatch Yönergesi

Açıklama: | URL’leri dosya sistemi konumlarıyla düzenli ifadeleri kullanarak eşler.
Sözdizimi: | AliasMatch "düzenli-ifade" "dosya-yolu|dizin-yolu"
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_alias

Bu yönerge URL-yolu ile eşleşmek üzere bir düzenli ifade kabul etmesi dışında Alias yönergesine eşdeğerdir. Belirtilen düzenli ifade URL-yolu ile eşleşiyorsa sunucu parantezli eşleşmeleri belirtilen dizgede kullanarak dosya yolunu elde eder. Örneğin, /icons dizinini etkinleştirmek için şu yazılabilir:

AliasMatch "^/icons(.*)" "/usr/local/apache/icons$1"

Düzenli ifadelerin tamamı kullanılabilmektedir. Örneğin, URL-yolu ile harf büyüklüğüne duyarsız eşleşmeler sağlayacak takma adlar kullanılabilir:

AliasMatch "(?i)^/image(.*)" "/ftp/pub/image$1"

Alias ve AliasMatch yönergeleri arasındaki başlıca fark Alias yönergesinin, URI'nin ek parçasını, eşleşen parçayı geçip sağ tarafta dosya yolunun ucuna kendiliğinden kopyalamasıdır. AliasMatch bunu böyle yapmaz. Yani hemen her durumda, düzenli ifadenin istenen URI'nin tamamıyla baştan sona eşleşmesi ve yer değiştirmeyi sağ tarafta yapması istenir.

Başka bir deyişle, basitçe Alias yerine AliasMatch yazmakla aynı etkiyi alamazsınız. En azından düzenli ifadenin başına bir ^ ve sonuna bir (.*)$, ikinci değiştirgenin sonuna da bir $1 eklemeniz gerekir.

Örneğin aşağıdakini AliasMatch ile değiştirmek isteyelim:

Alias "/image/" "/ftp/pub/image/"

Bu eşdeğer DEĞİLdir - bunu yapmayın! Bu herhangi bir yerinde /image/ dizgesi bulunan tüm istekleri /ftp/pub/image/ altına gönderecektir:

AliasMatch "/image/" "/ftp/pub/image/"

Aynı etkiyi elde etmek için bu gerekiyor:

AliasMatch "^/image/(.*)$" "/ftp/pub/image/$1"

Şüphesiz, Alias yönergesini çalıştığı yerde AliasMatch kullanmanın hiç gereği yoktur. AliasMatch daha karmaşık şeyler yapmamızı sağlar. Örneğin farklı dosya çeşitlerini farklı dizinlerden sunmak isteyelim:

AliasMatch "^/image/(.*)\.jpg$" "/files/jpg.images/$1.jpg"
AliasMatch "^/image/(.*)\.gif$" "/files/gif.images/$1.gif"

İstek URL'sinin başındaki bölü çizgileri, bu modüldeki yönergeler istek URL-yolu ile eşleştirilmeye çalışılmadan önce sunucu tarafından yokedilir.

Redirect Yönergesi

Açıklama: | İstemciyi, bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
Sözdizimi: | Redirect [durum] [URL-yolu] URL
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_alias

Redirect yönergesi istemciye bir yönlendirme isteği döndürerek eski URL’yi yenisiyle eşler.

Eski URL-yolu bir bölü çizgisi ile başlar ve harf büyüklüğüne duyarlıdır (% imlemesi çözüldükten sonra). URL-yolu olarak göreli yollara izin verilmez.

URL ise ya bir şema ve konak ismi ile başlayan bir mutlak URL ya da bir bölü çizgisi ile başlayan bir URL yolu olabilir. İkinci durumda URL yolunun başına geçerli sunucu ismi ve şemayı sunucu ekler.

URL-yolu ile başlayan istekler istemciye hedef URL konumuna bir yönlendirme isteği olarak dönecektir. URL-yolu’nun devamı niteliğindeki ek yol hedef URL’ye eklenir.

# Farklı bir konaktaki bir URL'ye yönlendirme
Redirect "/hizmet" "http://iki.example.com/hizmet"

# Aynı konak üzerinde yönlendirme
Redirect "/bir" "/iki"

İstemcinin yaptığı http://example.com/hizmet/fesmekan.txt isteğine karşılık istemciye isteği http://iki.example.com/hizmet/fesmekan.txt olarak yapması söylenecektir. Bu GET isteklerinde de geçerlidir. Örneğin, http://example.com/hizmet/foo.pl?q=23&a=42 isteği http://iki.example.com/hizmet/foo.pl?q=23&a=42 adresine yönlendirilir. POST'ların iptal edileceğini unutmayın.
Sadece tam yol parçaları eşleştirilir, bu nedenle http://example.com/hizmetfesmekan.txt isteği yukarıdaki yönlendirme ile eşleşmeyecektir. İfade sözdizimi kullanılan daha karmaşık eşleşmeler için URL-yolu seçeneği aşağıda açıklandığı gibi yoksayılır. Düzenli ifadelerin kullanıldığı daha karmaşık eşleşmeler için RedirectMatch yönergesine de bakınız.

Bilginize

Yapılandırma dosyasında yer alış sırasına bakmaksızın Redirect yönergeleri Alias ve ScriptAlias yönergelerinden önce ele alınır. <Location> bölümü içinde kullanılmış bir Redirect yönergesi URL-yolu belirtilmiş Redirect ve Alias yönergelerine göre önceliklidir.

Herhangi bir durum belirtilmemişse "geçici" yönlendirme (HTTP durum kodu: 302) yapılır. Bu, istemciye özkaynağın geçici olarak başka yere taşındığını belirtir. Diğer HTTP durum kodlarını döndürmek için kullanılabilecek durum değerleri:

permanent
İstemciye özkaynağın kalıcı olarak taşındığını belirten kalıcı yönlendirme durumu (301) döndürülür.
temp
İstemciye geçici yönlendirme durumu (302) döner. Bu öntanımlıdır.
seeother
İstemciye özkaynağın yerine başka bir şey konduğunu belirten "diğerine bak" durumu (303) döndürülür.
gone
İstemciye özkaynağın kalıcı olarak kaldırıldığını belirten "ölü bağlantı" durumu (410) döner. Bu durumda URL belirtilmez.

Diğer durum kodları için durum değiştirgesiyle sayısal durum kodu belirtilir. Eğer durum 300 ile 399 arasındaysa bir URL belirtmek gereklidir. Aksi takdirde, URL bileşeni ihmal edilmelidir. Belirtilecek durum kodunun geçerli bir HTTP Status kodu olmalı ve Apache HTTP Sunucusu kodu bilmelidir (http_protocol.c dosyasında bulunan send_error_response işlevine bakınız).

Redirect permanent "/bir" "http://example.com/iki"
Redirect 30" "/yedi" http://example.com/baskabisey"

Eğer Redirect yönergesi URL-yolu belirtilmemiş bir <Location> veya <LocationMatch> bölümü içinde yer alıyorsa, URL seçeneği ifade sözdizimi kullanılarak yorumlanır.
Bu sözdizimi Apache 2.4.19 ve sonrasında kullanılabilir.

<Location "/bir">
    Redirect permanent "http://example.com/iki"
</Location>
<Location "/yedi">
    Redirect 303 "http://example.com/baskabisey"
</Location>
<LocationMatch "/error/(?<NUMBER>[0-9]+)">
    Redirect permanent "http://example.com/errors/%{env:MATCH_NUMBER}.html"
</LocationMatch>

RedirectMatch Yönergesi

Açıklama: | Geçerli URL ile eşleşen bir düzenli ifadeye dayanarak bir harici yönlendirme gönderir.
Sözdizimi: | RedirectMatch [durum] düzenli-ifade URL
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_alias

Bu yönerge URL-yolu ile eşleşmek üzere bir düzenli ifade kabul etmesi dışında Redirect yönergesine eşdeğerdir. Belirtilen düzenli ifade URL-yolu ile eşleşiyorsa sunucu parantezli eşleşmeleri belirtilen dizgede kullanarak dosya yolunu elde eder. Örneğin, tüm GIF dosyası isteklerini başka bir sunucudaki aynı isimli JPEG dosyalarına yönlendirmek için şu yazılabilir:

RedirectMatch "(.*)\.gif$" "http://baska.example.com$1.jpg"

Alias ve AliasMatch arasındaki farklarla ilgili hususlar Redirect ve RedirectMatch arasındakilere de uygulanır. Ayrıntılar için AliasMatch yönergesine bakınız.

RedirectPermanent Yönergesi

Açıklama: | İstemciyi, kalıcı bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
Sözdizimi: | RedirectPermanent URL-yolu URL
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_alias

Bu yönerge istemciye daima kalıcı yönlendirme durumu (301) döndürür. Yani, Redirect permanent ile aynı işi yapar.

RedirectTemp Yönergesi

Açıklama: | İstemciyi, geçici bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
Sözdizimi: | RedirectTemp URL-yolu URL
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_alias

Bu yönerge istemciye daima geçici yönlendirme durumu (302) döndürür. Yani, Redirect temp ile aynı işi yapar.

ScriptAlias Yönergesi

Açıklama: | Bir URL’yi dosya sistemindeki bir yere eşler ve hedefi bir CGI betiği olarak çalıştırır.
Sözdizimi: | ScriptAlias [URL-yolu] dosya-yolu|dizin-yolu
Bağlam: | sunucu geneli, sanal konak, dizin
Durum: | Temel
Modül: | mod_alias

Hedef dizini, mod_cgi modülünün CGI betiği yorumlayıcısı tarafından çalıştırılacak betikleri içeren dizin olarak imlemesi dışında Alias yönergesinin yaptığı işi yapar. URL-yolu ile başlayan harf büyüklüğüne duyarlı URL’ler (% imlemesi çözüldükten sonra), dosya sistemindeki bir tam yol olarak belirtilmiş dizin-yolu ile başlayan betiklerle eşlenir.

ScriptAlias "/cgi-bin/" "/siteler/cgi-bin/"

http://example.com/cgi-bin/foo şeklindeki bir istek sunucunun /siteler/cgi-bin/foo betiğini çalıştırmasına sebep olur. Bu yapılandırma aslında şuna eşdeğerdir:

Alias "/cgi-bin/" "/siteler/cgi-bin/"
<Location "/cgi-bin">
    SetHandler cgi-script
    Options +ExecCGI
</Location>

ScriptAlias yönergesini bir betik veya eylemci ile birlikte de kullanabilirsiniz. Örnek:

ScriptAlias "/cgi-bin/" "/siteler/cgi-handler.pl"

Bu senaryoda /cgi-bin/’den istenen tüm dosyalar sizin belirttiğiniz dosya tarafından işleme sokulacaktır. Bu yöntemle kendi özel eylemcinizi kullanabilirsiniz. İsterseniz, bunu içerik eklemek ya da ısmarlama bir eylem için bir CGI sarmalayıcısı olarak da kullanabilirsiniz.

Yapılandırma değiştiğinde kaynak kodlarının ister istemez açığa çıkmasını istemiyorsanız CGI betiklerinizi DocumentRoot altına koymayınız. ScriptAlias yönergesi URL’yi doğru yere eşlemekten başka orayı bir CGI betikleri dizini olarak imler. CGI betiklerinizi DocumentRoot altına koyarsanız çalıştırmak için ScriptAlias değil, <Directory>, SetHandler ve Options yönergelerini örnekteki gibi kullanın:
<Directory "/usr/local/apache2/htdocs/cgi-bin" >
    SetHandler cgi-script
    Options ExecCGI
</Directory>
Aynı dosya sistemi konumu ile çok sayıda URL-yolu eşleşebileceğinden, bir Directory bölümü ile sınırlanmadığı takdirde CGI betiklerinin kaynak kodları açığa çıkabilir; bu bakımdan ScriptAlias yönergesini yok sayan URL yollarının belirtilebilme olasılığı gözardı edilmemelidir.

Eğer ScriptAlias yönergesi URL-yolu belirtilmemiş bir <Location> veya <LocationMatch> bölümü içinde yer alıyorsa, URL seçeneği ifade sözdizimi kullanılarak yorumlanır.
Bu sözdizimi Apache 2.4.19 ve sonrasında kullanılabilir.

<Location "/cgi-bin">
    ScriptAlias "/siteler/cgi-bin/"
</Location>
<LocationMatch "/cgi-bin/errors/(?<NUMBER>[0-9]+)">
    ScriptAlias "/siteler/cgi-bin/errors/%{env:MATCH_NUMBER}.cgi"
</LocationMatch>

Ayrıca bakınız:

  • CGI Öğreticisi

ScriptAliasMatch Yönergesi

Açıklama: | Bir URL’yi dosya sistemindeki bir yere düzenli ifade kullanarak eşler ve hedefi bir CGI betiği olarak çalıştırır.
Sözdizimi: | ScriptAliasMatch düzenli-ifade dosya-yolu|dizin-yolu
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_alias

Bu yönerge URL-yolu ile eşleşmek üzere bir düzenli ifade kabul etmesi dışında ScriptAlias yönergesine eşdeğerdir. Belirtilen düzenli ifade URL-yolu ile eşleşiyorsa sunucu parantezli eşleşmeleri belirtilen dizgede kullanarak dosya yolunu elde eder. Örneğin, standart /cgi-bin dizinini etkin kılmak için şu yazılabilir:

ScriptAliasMatch "^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"

AliasMatch yönergesindeki gibi, düzenli ifadelerin tamamı tüm güçleriyle kullanılabilmektedir. Örneğin, URL-yolu için harf büyüklüğüne duyarsız eşleşmeli bir takma ad oluşturmak mümkünür:

ScriptAliasMatch "(?i)^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"

Alias ve AliasMatch arasındaki farklarla ilgili hususlar ScriptAlias ve ScriptAliasMatch arasındakilere de uygulanır. Ayrıntılar için AliasMatch yönergesine bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_allowmethods - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_allowmethods

Description: | Easily restrict what HTTP methods can be used on the server
Status: | Experimental
Module Identifier: | allowmethods_module
Source File: | mod_allowmethods.c

Summary

This module makes it easy to restrict what HTTP methods can be used on a server. The most common configuration would be:

<Location "/">
   AllowMethods GET POST OPTIONS
</Location>

AllowMethods Directive

Description: | Restrict access to the listed HTTP methods
Syntax: | AllowMethods reset|HTTP-method [HTTP-method]...
Default: | AllowMethods reset
Context: | directory
Status: | Experimental
Module: | mod_allowmethods

The HTTP-methods are case sensitive and are generally, as per RFC, given in upper case. The GET and HEAD methods are treated as equivalent. The reset keyword can be used to turn off mod_allowmethods in a deeper nested context:

<Location "/svn">
   AllowMethods reset
</Location>

Caution

The TRACE method cannot be denied by this module; use TraceEnable instead.

mod_allowmethods was written to replace the rather kludgy implementation of Limit and LimitExcept.


mod_asis - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_asis

Description: | Sends files that contain their own HTTP headers
Status: | Base
Module Identifier: | asis_module
Source File: | mod_asis.c

Summary

This module provides the handler send-as-is which causes Apache HTTP Server to send the document without adding most of the usual HTTP headers.

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.

For historical reasons, this module will also process any file with the mime type httpd/send-as-is.

See also

  • mod_headers
  • mod_cern_meta
  • Apache httpd's Handler Use

Usage

In the server configuration file, associate files with the send-as-is handler e.g.

AddHandler send-as-is asis

The contents of any file with a .asis extension will then be sent by Apache httpd to the client with almost no changes. In particular, HTTP headers are derived from the file itself according to mod_cgi rules, so an asis file must include valid headers, and may also use the CGI Status: header to determine the HTTP response code. The Content-Length: header will automatically be inserted or, if included, corrected by httpd.

Here's an example of a file whose contents are sent as is so as to tell the client that a file has redirected.

Status: 301 Now where did I leave that URL
Location: http://xyz.example.com/foo/bar.html
Content-type: text/html

<html>
<head>
<title>Lame excuses'R'us</title>
</head>
<body>
<h1>Fred's exceptionally wonderful page has moved to
<a href="http://xyz.example.com/foo/bar.html">Joe's</a> site.
</h1>
</body>
</html>

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 not add a Last-Modified header; it probably should.


mod_auth_basic - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_auth_basic

Description: | Basic HTTP authentication
Status: | Base
Module Identifier: | auth_basic_module
Source File: | mod_auth_basic.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module allows the use of HTTP Basic Authentication to restrict access by looking up users in the given providers. HTTP Digest Authentication is provided by mod_auth_digest. This module should usually be combined with at least one authentication module such as mod_authn_file and one authorization module such as mod_authz_user.

See also

  • AuthName
  • AuthType
  • Require
  • Authentication howto

AuthBasicAuthoritative Directive

Description: | Sets whether authorization and authentication are passed to lower level modules
Syntax: | AuthBasicAuthoritative On|Off
Default: | AuthBasicAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_basic

Normally, each authorization module listed in AuthBasicProvider will attempt to verify the user, and if the user is not found in any provider, access will be denied. Setting the AuthBasicAuthoritative directive explicitly to Off allows for both authentication and authorization to be passed on to other non-provider-based modules if there is no userID or rule matching the supplied userID. This should only be necessary when combining mod_auth_basic with third-party modules that are not configured with the AuthBasicProvider directive. When using such modules, the order of processing is determined in the modules' source code and is not configurable.

AuthBasicFake Directive

Description: | Fake basic authentication using the given expressions for username and password
Syntax: | AuthBasicFake off|username [password]
Default: | none
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_basic
Compatibility: | Apache HTTP Server 2.4.5 and later

The username and password specified are combined into an Authorization header, which is passed to the server or service behind the webserver. Both the username and password fields are interpreted using the expression parser, which allows both the username and password to be set based on request parameters.

If the password is not specified, the default value "password" will be used. To disable fake basic authentication for an URL space, specify "AuthBasicFake off".

In this example, we pass a fixed username and password to a backend server.

Fixed Example

<Location "/demo">
    AuthBasicFake demo demopass
</Location>

In this example, we pass the email address extracted from a client certificate, extending the functionality of the FakeBasicAuth option within the SSLOptions directive. Like the FakeBasicAuth option, the password is set to the fixed string "password".

Certificate Example

<Location "/secure">
    AuthBasicFake "%{SSL_CLIENT_S_DN_Email}"
</Location>

Extending the above example, we generate a password by hashing the email address with a fixed passphrase, and passing the hash to the backend server. This can be used to gate into legacy systems that do not support client certificates.

Password Example

<Location "/secure">
    AuthBasicFake "%{SSL_CLIENT_S_DN_Email}" "%{sha1:passphrase-%{SSL_CLIENT_S_DN_Email}}"
</Location>

Exclusion Example

<Location "/public">
    AuthBasicFake off
</Location>

AuthBasicProvider Directive

Description: | Sets the authentication provider(s) for this location
Syntax: | AuthBasicProvider provider-name [provider-name] ...
Default: | AuthBasicProvider file
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_basic

The AuthBasicProvider directive sets which provider is used to authenticate the users for this location. The default file provider is implemented by the mod_authn_file module. Make sure that the chosen provider module is present in the server.

Example

<Location "/secure">
    AuthType basic
    AuthName "private area"
    AuthBasicProvider  dbm
    AuthDBMType        SDBM
    AuthDBMUserFile    "/www/etc/dbmpasswd"
    Require            valid-user
</Location>

Providers are queried in order until a provider finds a match for the requested username, at which point this sole provider will attempt to check the password. A failure to verify the password does not result in control being passed on to subsequent providers.

Providers are implemented by mod_authn_dbm, mod_authn_file, mod_authn_dbd, mod_authnz_ldap and mod_authn_socache.

AuthBasicUseDigestAlgorithm Directive

Description: | Check passwords against the authentication providers as if Digest Authentication was in force instead of Basic Authentication.
Syntax: | AuthBasicUseDigestAlgorithm MD5|Off
Default: | AuthBasicUseDigestAlgorithm Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_basic
Compatibility: | Apache HTTP Server 2.4.7 and later

Normally, when using Basic Authentication, the providers listed in AuthBasicProvider attempt to verify a user by checking their data stores for a matching username and associated password. The stored passwords are usually encrypted, but not necessarily so; each provider may choose its own storage scheme for passwords.

When using AuthDigestProvider and Digest Authentication, providers perform a similar check to find a matching username in their data stores. However, unlike in the Basic Authentication case, the value associated with each stored username must be an encrypted string composed from the username, realm name, and password. (See RFC 2617, Section 3.2.2.2 for more details on the format used for this encrypted string.)

As a consequence of the difference in the stored values between Basic and Digest Authentication, converting from Digest Authentication to Basic Authentication generally requires that all users be assigned new passwords, as their existing passwords cannot be recovered from the password storage scheme imposed on those providers which support Digest Authentication.

Setting the AuthBasicUseDigestAlgorithm directive to MD5 will cause the user's Basic Authentication password to be checked using the same encrypted format as for Digest Authentication. First a string composed from the username, realm name, and password is hashed with MD5; then the username and this encrypted string are passed to the providers listed in AuthBasicProvider as if AuthType was set to Digest and Digest Authentication was in force.

Through the use of AuthBasicUseDigestAlgorithm a site may switch from Digest to Basic Authentication without requiring users to be assigned new passwords.

The inverse process of switching from Basic to Digest Authentication without assigning new passwords is generally not possible. Only if the Basic Authentication passwords have been stored in plain text or with a reversable encryption scheme will it be possible to recover them and generate a new data store following the Digest Authentication password storage scheme.
Only providers which support Digest Authentication will be able to authenticate users when AuthBasicUseDigestAlgorithm is set to MD5. Use of other providers will result in an error response and the client will be denied access.


mod_auth_digest - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_auth_digest

Description: | User authentication using MD5 Digest Authentication
Status: | Extension
Module Identifier: | auth_digest_module
Source File: | mod_auth_digest.c

Summary

This module implements HTTP Digest Authentication (RFC2617), and provides an alternative to mod_auth_basic where the password is not transmitted as cleartext. However, this does not lead to a significant security advantage over basic authentication. On the other hand, the password storage on the server is much less secure with digest authentication than with basic authentication. Therefore, using basic auth and encrypting the whole connection using mod_ssl is a much better alternative.

See also

  • AuthName
  • AuthType
  • Require
  • Authentication howto

Using Digest Authentication

To use MD5 Digest authentication, simply change the normal AuthType Basic and AuthBasicProvider to AuthType Digest and AuthDigestProvider, when setting up authentication, then add a AuthDigestDomain directive containing at least the root URI(s) for this protection space.

Appropriate user (text) files can be created using the htdigest tool.

Example:

<Location "/private/">
    AuthType Digest
    AuthName "private area"
    AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"

    AuthDigestProvider file
    AuthUserFile "/web/auth/.digest_pw"
    Require valid-user
</Location>

Note

Digest authentication was intended to be more secure than basic authentication, but no longer fulfills that design goal. A man-in-the-middle attacker can trivially force the browser to downgrade to basic authentication. And even a passive eavesdropper can brute-force the password using today's graphics hardware, because the hashing algorithm used by digest authentication is too fast. Another problem is that the storage of the passwords on the server is insecure. The contents of a stolen htdigest file can be used directly for digest authentication. Therefore using mod_ssl to encrypt the whole connection is strongly recommended.

mod_auth_digest only works properly on platforms where APR supports shared memory.

AuthDigestAlgorithm Directive

Description: | Selects the algorithm used to calculate the challenge and response hashes in digest authentication
Syntax: | AuthDigestAlgorithm MD5|MD5-sess
Default: | AuthDigestAlgorithm MD5
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestAlgorithm directive selects the algorithm used to calculate the challenge and response hashes.

MD5-sess is not correctly implemented yet.

AuthDigestDomain Directive

Description: | URIs that are in the same protection space for digest authentication
Syntax: | AuthDigestDomain URI [URI] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestDomain 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; 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. including a scheme, host, port, etc.) or relative URIs.

This directive should 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 every request sent to this server.

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.

AuthDigestNonceLifetime Directive

Description: | How long the server nonce is valid
Syntax: | AuthDigestNonceLifetime seconds
Default: | AuthDigestNonceLifetime 300
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestNonceLifetime 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 stale=true. If seconds 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 seconds is less than 0 then the nonce never expires.

AuthDigestProvider Directive

Description: | Sets the authentication provider(s) for this location
Syntax: | AuthDigestProvider provider-name [provider-name] ...
Default: | AuthDigestProvider file
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestProvider directive sets which provider is used to authenticate the users for this location. The default file provider is implemented by the mod_authn_file module. Make sure that the chosen provider module is present in the server.

See mod_authn_dbm, mod_authn_file, mod_authn_dbd and mod_authn_socache for providers.

AuthDigestQop Directive

Description: | Determines the quality-of-protection to use in digest authentication
Syntax: | AuthDigestQop none|auth|auth-int [auth|auth-int]
Default: | AuthDigestQop auth
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestQop directive determines the quality-of-protection to use. auth will only do authentication (username/password); auth-int is authentication plus integrity checking (an MD5 hash of the entity is also computed and checked); none will cause the module to use the old RFC-2069 digest algorithm (which does not include integrity checking). Both auth and auth-int may be specified, in which the case the browser will choose which of these to use. none should only be used if the browser for some reason does not like the challenge it receives otherwise.

auth-int is not implemented yet.

AuthDigestShmemSize Directive

Description: | The amount of shared memory to allocate for keeping track of clients
Syntax: | AuthDigestShmemSize size
Default: | AuthDigestShmemSize 1000
Context: | server config
Status: | Extension
Module: | mod_auth_digest

The AuthDigestShmemSize directive defines the amount of shared memory, that will be allocated at the server startup for keeping track of clients. Note that the shared memory segment cannot be set less than the space that is necessary for tracking at least one client. This value is dependent on your system. If you want to find out the exact value, you may simply set AuthDigestShmemSize to the value of 0 and read the error message after trying to start the server.

The size is normally expressed in Bytes, but you may follow the number with a K or an M to express your value as KBytes or MBytes. For example, the following directives are all equivalent:

AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_auth_form - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_auth_form

Description: | Form authentication
Status: | Base
Module Identifier: | auth_form_module
Source File: | mod_auth_form.c
Compatibility: | Available in Apache 2.3 and later

Summary

Warning

Form authentication depends on the mod_session modules, and these modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This module allows the use of an HTML login form to restrict access by looking up users in the given providers. HTML forms require significantly more configuration than the alternatives, however an HTML login form can provide a much friendlier experience for end users.

HTTP basic authentication is provided by mod_auth_basic, and HTTP digest authentication is provided by mod_auth_digest. This module should be combined with at least one authentication module such as mod_authn_file and one authorization module such as mod_authz_user.

Once the user has been successfully authenticated, the user's login details will be stored in a session provided by mod_session.

See also

  • mod_session
  • AuthName
  • AuthType
  • Require
  • Authentication howto

Basic Configuration

To protect a particular URL with mod_auth_form, you need to decide where you will store your session, and you will need to decide what method you will use to authenticate. In this simple example, the login details will be stored in a session based on mod_session_cookie, and authentication will be attempted against a file using mod_authn_file. If authentication is unsuccessful, the user will be redirected to the form login page.

Basic example

AuthFormProvider file
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
AuthFormLoginRequiredLocation "http://example.com/login.html"
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

The directive AuthType will enable the mod_auth_form authentication when set to the value form. The directives AuthFormProvider and AuthUserFile specify that usernames and passwords should be checked against the chosen file.

The directives Session, SessionCookieName and SessionCryptoPassphrase create an encrypted session stored within an HTTP cookie on the browser. For more information on the different options for configuring a session, read the documentation for mod_session.

In the simple example above, a URL has been protected by mod_auth_form, but the user has yet to be given an opportunity to enter their username and password. Options for doing so include providing a dedicated standalone login page for this purpose, or for providing the login page inline.

Standalone Login

The login form can be hosted as a standalone page, or can be provided inline on the same page.

When configuring the login as a standalone page, unsuccessful authentication attempts should be redirected to a login form created by the website for this purpose, using the AuthFormLoginRequiredLocation directive. Typically this login page will contain an HTML form, asking the user to provide their usename and password.

Example login form

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

The part that does the actual login is handled by the form-login-handler. The action of the form should point at this handler, which is configured within Apache httpd as follows:

Form login handler example

<Location "/dologin.html">
    SetHandler form-login-handler
    AuthFormLoginRequiredLocation "http://example.com/login.html"
    AuthFormLoginSuccessLocation "http://example.com/success.html"
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName realm
    Session On
    SessionCookieName session path=/
    SessionCryptoPassphrase secret
</Location>

The URLs specified by the AuthFormLoginRequiredLocation directive will typically point to a page explaining to the user that their login attempt was unsuccessful, and they should try again. The AuthFormLoginSuccessLocation directive specifies the URL the user should be redirected to upon successful login.

Alternatively, the URL to redirect the user to on success can be embedded within the login form, as in the example below. As a result, the same form-login-handler can be reused for different areas of a website.

Example login form with location

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
  <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
</form>

Inline Login

Warning

A risk exists that under certain circumstances, the login form configured using inline login may be submitted more than once, revealing login credentials to the application running underneath. The administrator must ensure that the underlying application is properly secured to prevent abuse. If in doubt, use the standalone login configuration.

As an alternative to having a dedicated login page for a website, it is possible to configure mod_auth_form to authenticate users inline, without being redirected to another page. This allows the state of the current page to be preserved during the login attempt. This can be useful in a situation where a time limited session is in force, and the session times out in the middle of the user request. The user can be re-authenticated in place, and they can continue where they left off.

If a non-authenticated user attempts to access a page protected by mod_auth_form that isn't configured with a AuthFormLoginRequiredLocation directive, a HTTP_UNAUTHORIZED status code is returned to the browser indicating to the user that they are not authorized to view the page.

To configure inline authentication, the administrator overrides the error document returned by the HTTP_UNAUTHORIZED status code with a custom error document containing the login form, as follows:

Basic inline example

AuthFormProvider file
ErrorDocument 401 "/login.shtml"
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
AuthFormLoginRequiredLocation "http://example.com/login.html"
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

The error document page should contain a login form with an empty action property, as per the example below. This has the effect of submitting the form to the original protected URL, without the page having to know what that URL is.

Example inline login form

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

When the end user has filled in their login details, the form will make an HTTP POST request to the original password protected URL. mod_auth_form will intercept this POST request, and if HTML fields are found present for the username and password, the user will be logged in, and the original password protected URL will be returned to the user as a GET request.

Inline Login with Body Preservation

A limitation of the inline login technique described above is that should an HTML form POST have resulted in the request to authenticate or reauthenticate, the contents of the original form posted by the browser will be lost. Depending on the function of the website, this could present significant inconvenience for the end user.

mod_auth_form addresses this by allowing the method and body of the original request to be embedded in the login form. If authentication is successful, the original method and body will be retried by Apache httpd, preserving the state of the original request.

To enable body preservation, add three additional fields to the login form as per the example below.

Example with body preservation

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />

  <input type="hidden" name="httpd_method" value="POST" />
  <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
  <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" />

</form>

How the method, mimetype and body of the original request are embedded within the login form will depend on the platform and technology being used within the website.

One option is to use the mod_include module along with the KeptBodySize directive, along with a suitable CGI script to embed the variables in the form.

Another option is to render the login form using a CGI script or other dynamic technology.

CGI example

        AuthFormProvider file
        ErrorDocument 401 "/cgi-bin/login.cgi"
        ...

Logging Out

To enable a user to log out of a particular session, configure a page to be handled by the form-logout-handler. Any attempt to access this URL will cause the username and password to be removed from the current session, effectively logging the user out.

By setting the AuthFormLogoutLocation directive, a URL can be specified that the browser will be redirected to on successful logout. This URL might explain to the user that they have been logged out, and give the user the option to log in again.

Basic logout example

SetHandler form-logout-handler
AuthName realm
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

Note that logging a user out does not delete the session; it merely removes the username and password from the session. If this results in an empty session, the net effect will be the removal of that session, but this is not guaranteed. If you want to guarantee the removal of a session, set the SessionMaxAge directive to a small value, like 1 (setting the directive to zero would mean no session age limit).

Basic session expiry example

SetHandler form-logout-handler
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionMaxAge 1
SessionCookieName session path=/
SessionCryptoPassphrase secret

Usernames and Passwords

Note that form submission involves URLEncoding the form data: in this case the username and password. You should therefore pick usernames and passwords that avoid characters that are URLencoded in form submission, or you may get unexpected results.

AuthFormAuthoritative Directive

Description: | Sets whether authorization and authentication are passed to lower level modules
Syntax: | AuthFormAuthoritative On|Off
Default: | AuthFormAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_form

Normally, each authorization module listed in AuthFormProvider will attempt to verify the user, and if the user is not found in any provider, access will be denied. Setting the AuthFormAuthoritative directive explicitly to Off allows for both authentication and authorization to be passed on to other non-provider-based modules if there is no userID or rule matching the supplied userID. This should only be necessary when combining mod_auth_form with third-party modules that are not configured with the AuthFormProvider directive. When using such modules, the order of processing is determined in the modules' source code and is not configurable.

AuthFormBody Directive

Description: | The name of a form field carrying the body of the request to attempt on successful login
Syntax: | AuthFormBody fieldname
Default: | httpd_body
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormMethod directive specifies the name of an HTML field which, if present, will contain the method of the request to to submit should login be successful.

By populating the form with fields described by AuthFormMethod, AuthFormMimetype and AuthFormBody, a website can retry a request that may have been interrupted by the login screen, or by a session timeout.

AuthFormDisableNoStore Directive

Description: | Disable the CacheControl no-store header on the login page
Syntax: | AuthFormDisableNoStore On|Off
Default: | AuthFormDisableNoStore Off
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormDisableNoStore flag disables the sending of a Cache-Control no-store header with the error 401 page returned when the user is not yet logged in. The purpose of the header is to make it difficult for an ecmascript application to attempt to resubmit the login form, and reveal the username and password to the backend application. Disable at your own risk.

AuthFormFakeBasicAuth Directive

Description: | Fake a Basic Authentication header
Syntax: | AuthFormFakeBasicAuth On|Off
Default: | AuthFormFakeBasicAuth Off
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormFakeBasicAuth flag determines whether a Basic Authentication header will be added to the request headers. This can be used to expose the username and password to an underlying application, without the underlying application having to be aware of how the login was achieved.

AuthFormLocation Directive

Description: | The name of a form field carrying a URL to redirect to on successful login
Syntax: | AuthFormLocation fieldname
Default: | httpd_location
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormLocation directive specifies the name of an HTML field which, if present, will contain a URL to redirect the browser to should login be successful.

AuthFormLoginRequiredLocation Directive

Description: | The URL of the page to be redirected to should login be required
Syntax: | AuthFormLoginRequiredLocation url
Default: | none
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later. The use of the expression parser has been added in 2.4.4.

The AuthFormLoginRequiredLocation directive specifies the URL to redirect to should the user not be authorised to view a page. The value is parsed using the ap_expr parser before being sent to the client. By default, if a user is not authorised to view a page, the HTTP response code HTTP_UNAUTHORIZED will be returned with the page specified by the ErrorDocument directive. This directive overrides this default.

Use this directive if you have a dedicated login page to redirect users to.

AuthFormLoginSuccessLocation Directive

Description: | The URL of the page to be redirected to should login be successful
Syntax: | AuthFormLoginSuccessLocation url
Default: | none
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later. The use of the expression parser has been added in 2.4.4.

The AuthFormLoginSuccessLocation directive specifies the URL to redirect to should the user have logged in successfully. The value is parsed using the ap_expr parser before being sent to the client. This directive can be overridden if a form field has been defined containing another URL using the AuthFormLocation directive.

Use this directive if you have a dedicated login URL, and you have not embedded the destination page in the login form.

AuthFormLogoutLocation Directive

Description: | The URL to redirect to after a user has logged out
Syntax: | AuthFormLogoutLocation uri
Default: | none
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later. The use of the expression parser has been added in 2.4.4.

The AuthFormLogoutLocation directive specifies the URL of a page on the server to redirect to should the user attempt to log out. The value is parsed using the ap_expr parser before being sent to the client.

When a URI is accessed that is served by the handler form-logout-handler, the page specified by this directive will be shown to the end user. For example:

Example

<Location "/logout">
    SetHandler form-logout-handler
    AuthFormLogoutLocation "http://example.com/loggedout.html"
    Session on
    #...
</Location>

An attempt to access the URI /logout/ will result in the user being logged out, and the page /loggedout.html will be displayed. Make sure that the page loggedout.html is not password protected, otherwise the page will not be displayed.

AuthFormMethod Directive

Description: | The name of a form field carrying the method of the request to attempt on successful login
Syntax: | AuthFormMethod fieldname
Default: | httpd_method
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormMethod directive specifies the name of an HTML field which, if present, will contain the method of the request to to submit should login be successful.

By populating the form with fields described by AuthFormMethod, AuthFormMimetype and AuthFormBody, a website can retry a request that may have been interrupted by the login screen, or by a session timeout.

AuthFormMimetype Directive

Description: | The name of a form field carrying the mimetype of the body of the request to attempt on successful login
Syntax: | AuthFormMimetype fieldname
Default: | httpd_mimetype
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormMethod directive specifies the name of an HTML field which, if present, will contain the mimetype of the request to submit should login be successful.

By populating the form with fields described by AuthFormMethod, AuthFormMimetype and AuthFormBody, a website can retry a request that may have been interrupted by the login screen, or by a session timeout.

AuthFormPassword Directive

Description: | The name of a form field carrying the login password
Syntax: | AuthFormPassword fieldname
Default: | httpd_password
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormPassword directive specifies the name of an HTML field which, if present, will contain the password to be used to log in.

AuthFormProvider Directive

Description: | Sets the authentication provider(s) for this location
Syntax: | AuthFormProvider provider-name [provider-name] ...
Default: | AuthFormProvider file
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth_form

The AuthFormProvider directive sets which provider is used to authenticate the users for this location. The default file provider is implemented by the mod_authn_file module. Make sure that the chosen provider module is present in the server.

Example

<Location "/secure">
    AuthType form
    AuthName "private area"
    AuthFormProvider  dbm
    AuthDBMType        SDBM
    AuthDBMUserFile    "/www/etc/dbmpasswd"
    Require            valid-user
    #...
</Location>

Providers are implemented by mod_authn_dbm, mod_authn_file, mod_authn_dbd, mod_authnz_ldap and mod_authn_socache.

AuthFormSitePassphrase Directive

Description: | Bypass authentication checks for high traffic sites
Syntax: | AuthFormSitePassphrase secret
Default: | none
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormSitePassphrase directive specifies a passphrase which, if present in the user session, causes Apache httpd to bypass authentication checks for the given URL. It can be used on high traffic websites to reduce the load induced on authentication infrastructure.

The passphrase can be inserted into a user session by adding this directive to the configuration for the form-login-handler. The form-login-handler itself will always run the authentication checks, regardless of whether a passphrase is specified or not.

Warning

If the session is exposed to the user through the use of mod_session_cookie, and the session is not protected with mod_session_crypto, the passphrase is open to potential exposure through a dictionary attack. Regardless of how the session is configured, ensure that this directive is not used within URL spaces where private user data could be exposed, or sensitive transactions can be conducted. Use at own risk.

AuthFormSize Directive

Description: | The largest size of the form in bytes that will be parsed for the login details
Syntax: | AuthFormSize size
Default: | 8192
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormSize directive specifies the maximum size of the body of the request that will be parsed to find the login form.

If a login request arrives that exceeds this size, the whole request will be aborted with the HTTP response code HTTP_REQUEST_TOO_LARGE.

If you have populated the form with fields described by AuthFormMethod, AuthFormMimetype and AuthFormBody, you probably want to set this field to a similar size as the KeptBodySize directive.

AuthFormUsername Directive

Description: | The name of a form field carrying the login username
Syntax: | AuthFormUsername fieldname
Default: | httpd_username
Context: | directory
Status: | Base
Module: | mod_auth_form
Compatibility: | Available in Apache HTTP Server 2.3.0 and later

The AuthFormUsername directive specifies the name of an HTML field which, if present, will contain the username to be used to log in.


mod_authn_anon - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_anon

Description: | Allows "anonymous" user access to authenticated areas
Status: | Extension
Module Identifier: | authn_anon_module
Source File: | mod_authn_anon.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_basic to authenticate users similar to anonymous-ftp sites, i.e. have a 'magic' user id 'anonymous' and the email address as a password. These email addresses can be logged.

Combined with other (database) access control methods, this allows for effective user tracking and customization according to a user profile while still keeping the site open for 'unregistered' users. One advantage of using Auth-based user tracking is that, unlike magic-cookies and funny URL pre/postfixes, it is completely browser independent and it allows users to share URLs.

When using mod_auth_basic, this module is invoked via the AuthBasicProvider directive with the anon value.

Example

The example below is combined with "normal" htpasswd-file based authentication and allows users in additionally as 'guests' with the following properties:

  • It insists that the user enters a userID. (Anonymous_NoUserID)
  • It insists that the user enters a password. (Anonymous_MustGiveEmail)
  • The password entered must be a valid email address, i.e. contain at least one '@' and a '.'. (Anonymous_VerifyEmail)
  • The userID must be one of anonymous guest www test welcome and comparison is not case sensitive. (Anonymous)
  • And the Email addresses entered in the passwd field are logged to the error log file. (Anonymous_LogEmail)

Example

<Directory "/var/www/html/private">
    AuthName "Use 'anonymous' & Email address for guest entry"
    AuthType Basic
    AuthBasicProvider file anon
    AuthUserFile "/path/to/your/.htpasswd"

    Anonymous_NoUserID off
    Anonymous_MustGiveEmail on
    Anonymous_VerifyEmail on
    Anonymous_LogEmail on
    Anonymous anonymous guest www test welcome

    Require valid-user
</Directory>

Anonymous Directive

Description: | Specifies userIDs that are allowed access without password verification
Syntax: | Anonymous user [user] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_anon

A list of one or more 'magic' userIDs which are allowed access without password verification. The userIDs are space separated. It is possible to use the ' and " quotes to allow a space in a userID as well as the \ escape character.

Please note that the comparison is case-IN-sensitive.
It's strongly recommended that the magic username 'anonymous' is always one of the allowed userIDs.

Example:

Anonymous anonymous "Not Registered" "I don't know"

This would allow the user to enter without password verification by using the userIDs "anonymous", "AnonyMous", "Not Registered" and "I Don't Know".

As of Apache 2.1 it is possible to specify the userID as "*". That allows any supplied userID to be accepted.

Anonymous_LogEmail Directive

Description: | Sets whether the password entered will be logged in the error log
Syntax: | Anonymous_LogEmail On|Off
Default: | Anonymous_LogEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_anon

When set On, the default, the 'password' entered (which hopefully contains a sensible email address) is logged in the error log.

Anonymous_MustGiveEmail Directive

Description: | Specifies whether blank passwords are allowed
Syntax: | Anonymous_MustGiveEmail On|Off
Default: | Anonymous_MustGiveEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_anon

Specifies whether the user must specify an email address as the password. This prohibits blank passwords.

Anonymous_NoUserID Directive

Description: | Sets whether the userID field may be empty
Syntax: | Anonymous_NoUserID On|Off
Default: | Anonymous_NoUserID Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_anon

When set On, users can leave the userID (and perhaps the password field) empty. This can be very convenient for MS-Explorer users who can just hit return or click directly on the OK button; which seems a natural reaction.

Anonymous_VerifyEmail Directive

Description: | Sets whether to check the password field for a correctly formatted email address
Syntax: | Anonymous_VerifyEmail On|Off
Default: | Anonymous_VerifyEmail Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_anon

When set On the 'password' entered is checked for at least one '@' and a '.' to encourage users to enter valid email addresses (see the above Anonymous_LogEmail).


mod_authn_core - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_core

Description: | Core Authentication
Status: | Base
Module Identifier: | authn_core_module
Source File: | mod_authn_core.c
Compatibility: | Available in Apache 2.3 and later

Summary

This module provides core authentication capabilities to allow or deny access to portions of the web site. mod_authn_core provides directives that are common to all authentication providers.

Creating Authentication Provider Aliases

Extended authentication providers can be created within the configuration file and assigned an alias name. The alias providers can then be referenced through the directives AuthBasicProvider or AuthDigestProvider in the same way as a base authentication provider. Besides the ability to create and alias an extended provider, it also allows the same extended authentication provider to be reference by multiple locations.

Examples

This example checks for passwords in two different text files.

Checking multiple text password files

# Check here first
<AuthnProviderAlias file file1>
    AuthUserFile "/www/conf/passwords1"
</AuthnProviderAlias>

# Then check here
<AuthnProviderAlias file file2>
    AuthUserFile "/www/conf/passwords2"
</AuthnProviderAlias>

<Directory "/var/web/pages/secure">
    AuthBasicProvider file1 file2

    AuthType Basic
    AuthName "Protected Area"
    Require valid-user
</Directory>

The example below creates two different ldap authentication provider aliases based on the ldap provider. This allows a single authenticated location to be serviced by multiple ldap hosts:

Checking multiple LDAP servers

<AuthnProviderAlias ldap ldap-alias1>
    AuthLDAPBindDN cn=youruser,o=ctx
    AuthLDAPBindPassword yourpassword
    AuthLDAPURL ldap://ldap.host/o=ctx
</AuthnProviderAlias>
<AuthnProviderAlias ldap ldap-other-alias>
    AuthLDAPBindDN cn=yourotheruser,o=dev
    AuthLDAPBindPassword yourotherpassword
    AuthLDAPURL ldap://other.ldap.host/o=dev?cn
</AuthnProviderAlias>

Alias "/secure" "/webpages/secure"
<Directory "/webpages/secure">
    AuthBasicProvider ldap-other-alias  ldap-alias1

    AuthType Basic
    AuthName "LDAP Protected Place"
    Require valid-user
    # Note that Require ldap-* would not work here, since the
    # AuthnProviderAlias does not provide the config to authorization providers
    # that are implemented in the same module as the authentication provider.
</Directory>

AuthName Directive

Description: | Authorization realm for use in HTTP authentication
Syntax: | AuthName auth-domain
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authn_core

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. AuthName takes a single argument; if the realm name contains spaces, it must be enclosed in quotation marks. It must be accompanied by AuthType and Require directives, and directives such as AuthUserFile and AuthGroupFile to work.

For example:

AuthName "Top Secret"

The string provided for the AuthName is what will appear in the password dialog provided by most browsers.

See also

  • Authentication, Authorization, and Access Control
  • mod_authz_core

<AuthnProviderAlias> Directive

Description: | Enclose a group of directives that represent an extension of a base authentication provider and referenced by the specified alias
Syntax: | <AuthnProviderAlias baseProvider Alias> ... </AuthnProviderAlias>
Context: | server config
Status: | Base
Module: | mod_authn_core

<AuthnProviderAlias> and </AuthnProviderAlias> are used to enclose a group of authentication directives that can be referenced by the alias name using one of the directives AuthBasicProvider or AuthDigestProvider.

This directive has no affect on authorization, even for modules that provide both authentication and authorization.

AuthType Directive

Description: | Type of user authentication
Syntax: | AuthType None|Basic|Digest|Form
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authn_core

This directive selects the type of user authentication for a directory. The authentication types available are None, Basic (implemented by mod_auth_basic), Digest (implemented by mod_auth_digest), and Form (implemented by mod_auth_form).

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.

The authentication type None disables authentication. When authentication is enabled, it is normally inherited by each subsequent configuration section, unless a different authentication type is specified. If no authentication is desired for a subsection of an authenticated section, the authentication type None may be used; in the following example, clients may access the /www/docs/public directory without authenticating:

<Directory "/www/docs">
    AuthType Basic
    AuthName Documents
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    Require valid-user
</Directory>

<Directory "/www/docs/public">
    AuthType None
    Require all granted
</Directory>
When disabling authentication, note that clients which have already authenticated against another portion of the server's document tree will typically continue to send authentication HTTP headers or cookies with each request, regardless of whether the server actually requires authentication for every resource.

See also

  • Authentication, Authorization, and Access Control


mod_authn_dbd - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_dbd

Description: | User authentication using an SQL database
Status: | Extension
Module Identifier: | authn_dbd_module
Source File: | mod_authn_dbd.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic to authenticate users by looking up users in SQL tables. Similar functionality is provided by, for example, mod_authn_file.

This module relies on mod_dbd to specify the backend database driver and connection parameters, and manage the database connections.

When using mod_auth_basic or mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider with the dbd value.

See also

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider
  • DBDriver
  • DBDParams
  • Password Formats

Performance and Cacheing

Some users of DBD authentication in HTTPD 2.2/2.4 have reported that it imposes a problematic load on the database. This is most likely where an HTML page contains hundreds of objects (e.g. images, scripts, etc) each of which requires authentication. Users affected (or concerned) by this kind of problem should use mod_authn_socache to cache credentials and take most of the load off the database.

Configuration Example

This simple example shows use of this module in the context of the Authentication and DBD frameworks.

# mod_dbd configuration
# UPDATED to include authentication cacheing
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache password=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory "/usr/www/myhost/private">
  # mod_authn_core and mod_auth_basic configuration
  # for mod_authn_dbd
  AuthType Basic
  AuthName "My Server"

  # To cache credentials, put socache ahead of dbd here
  AuthBasicProvider socache dbd

  # Also required for caching: tell the cache to cache dbd lookups!
  AuthnCacheProvideFor dbd
  AuthnCacheContext my-server

  # mod_authz_core configuration
  Require valid-user

  # mod_authn_dbd SQL query to authenticate a user
  AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
</Directory>

Exposing Login Information

If httpd was built against APR version 1.3.0 or higher, then whenever a query is made to the database server, all column values in the first row returned by the query are placed in the environment, using environment variables with the prefix "AUTHENTICATE_".

If a database query for example returned the username, full name and telephone number of a user, a CGI program will have access to this information without the need to make a second independent database query to gather this additional information.

This has the potential to dramatically simplify the coding and configuration required in some web applications.

AuthDBDUserPWQuery Directive

Description: | SQL query to look up a password for a user
Syntax: | AuthDBDUserPWQuery query
Context: | directory
Status: | Extension
Module: | mod_authn_dbd

The AuthDBDUserPWQuery specifies an SQL query to look up a password for a specified user. The user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a %s format specifier.

AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

The first column value of the first row returned by the query statement should be a string containing the encrypted password. Subsequent rows will be ignored. If no rows are returned, the user will not be authenticated through mod_authn_dbd.

If httpd was built against APR version 1.3.0 or higher, any additional column values in the first row returned by the query statement will be stored as environment variables with names of the form AUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.

AuthDBDUserRealmQuery Directive

Description: | SQL query to look up a password hash for a user and realm.
Syntax: | AuthDBDUserRealmQuery query
Context: | directory
Status: | Extension
Module: | mod_authn_dbd

The AuthDBDUserRealmQuery specifies an SQL query to look up a password for a specified user and realm in a digest authentication process. The user's ID and the realm, in that order, will be passed as string parameters when the SQL query is executed. They may be referenced within the query statement using %s format specifiers.

AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"

The first column value of the first row returned by the query statement should be a string containing the encrypted password. Subsequent rows will be ignored. If no rows are returned, the user will not be authenticated through mod_authn_dbd.

If httpd was built against APR version 1.3.0 or higher, any additional column values in the first row returned by the query statement will be stored as environment variables with names of the form AUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.


mod_authn_dbm - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_dbm

Description: | User authentication using DBM files
Status: | Extension
Module Identifier: | authn_dbm_module
Source File: | mod_authn_dbm.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic to authenticate users by looking up users in dbm password files. Similar functionality is provided by mod_authn_file.

When using mod_auth_basic or mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider with the dbm value.

See also

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider
  • htpasswd
  • htdbm
  • Password Formats

AuthDBMType Directive

Description: | Sets the type of database file that is used to store passwords
Syntax: | AuthDBMType default|SDBM|GDBM|NDBM|DB
Default: | AuthDBMType default
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_dbm

Sets the type of database file that is used to store the passwords. The default database type is determined at compile time. The availability of other types of database files also depends on compile-time settings.

It is crucial that whatever program you use to create your password files is configured to use the same type of database.

AuthDBMUserFile Directive

Description: | Sets the name of a database file containing the list of users and passwords for authentication
Syntax: | AuthDBMUserFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_dbm

The AuthDBMUserFile directive sets the name of a DBM file containing the list of users and passwords for user authentication. File-path is the absolute path to the user file.

The user file is keyed on the username. The value for a user is the encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

Security:

Make sure that the AuthDBMUserFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMUserFile.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.

Important compatibility note: The implementation of dbmopen in the apache modules reads the string length of the hashed values from the DBM data structures, rather than relying upon the string being NULL-appended. Some applications, such as the Netscape web server, rely upon the string being NULL-appended, so if you are having trouble using DBM files interchangeably between applications this may be a part of the problem.

A perl script called dbmmanage is included with Apache. This program can be used to create and update DBM format password files for use with this module. Another tool for maintaining the DBM files is the included program htdbm.


mod_authn_file - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_file

Description: | User authentication using text files
Status: | Base
Module Identifier: | authn_file_module
Source File: | mod_authn_file.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic to authenticate users by looking up users in plain text password files. Similar functionality is provided by mod_authn_dbm.

When using mod_auth_basic or mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider with the file value.

See also

  • AuthBasicProvider
  • AuthDigestProvider
  • htpasswd
  • htdigest
  • Password Formats

AuthUserFile Directive

Description: | Sets the name of a text file containing the list of users and passwords for authentication
Syntax: | AuthUserFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authn_file

The AuthUserFile directive sets the name of a textual file containing the list of users and passwords for user authentication. File-path is the path to the user file. If it is not absolute, it is treated as relative to the ServerRoot.

Each line of the user file contains a username followed by a colon, followed by the encrypted password. If the same user ID is defined multiple times, mod_authn_file will use the first occurrence to verify the password.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.

For mod_auth_basic, use the utility htpasswd which is installed as part of the binary distribution, or which can be found in src/support. See the man page for more details. In short:

Create a password file Filename with username as the initial ID. It will prompt for the password:

htpasswd -c Filename username

Add or modify username2 in the password file Filename:

htpasswd Filename username2

Note that searching large text files is very inefficient; AuthDBMUserFile should be used instead.

For mod_auth_digest, use htdigest instead. Note that you cannot mix user data for Digest Authentication and Basic Authentication within the same file.

Security

Make sure that the AuthUserFile is stored outside the document tree of the web-server. Do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthUserFile.


mod_authn_socache - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authn_socache

Description: | Manages a cache of authentication credentials to relieve the load on backends
Status: | Base
Module Identifier: | authn_socache_module
Source File: | mod_authn_socache.c
Compatibility: | Version 2.3 and later

Summary

Maintains a cache of authentication credentials, so that a new backend lookup is not required for every authenticated request.

Authentication Cacheing

Some users of more heavyweight authentication such as SQL database lookups (mod_authn_dbd) have reported it putting an unacceptable load on their authentication provider. A typical case in point is where an HTML page contains hundreds of objects (images, scripts, stylesheets, media, etc), and a request to the page generates hundreds of effectively-immediate requests for authenticated additional contents.

mod_authn_socache provides a solution to this problem by maintaining a cache of authentication credentials.

Usage

The authentication cache should be used where authentication lookups impose a significant load on the server, or a backend or network. Authentication by file (mod_authn_file) or dbm (mod_authn_dbm) are unlikely to benefit, as these are fast and lightweight in their own right (though in some cases, such as a network-mounted file, cacheing may be worthwhile). Other providers such as SQL or LDAP based authentication are more likely to benefit, particularly where there is an observed performance issue. Amongst the standard modules, mod_authnz_ldap manages its own cache, so only mod_authn_dbd will usually benefit from this cache.

The basic rules to cache for a provider are:

  1. Include the provider you're cacheing for in an AuthnCacheProvideFor directive.
  2. List socache ahead of the provider you're cacheing for in your AuthBasicProvider or AuthDigestProvider directive.

A simple usage example to accelerate mod_authn_dbd using dbm as a cache engine:

#AuthnCacheSOCache is optional.  If specified, it is server-wide
AuthnCacheSOCache dbm
<Directory "/usr/www/myhost/private">
    AuthType Basic
    AuthName "Cached Authentication Example"
    AuthBasicProvider socache dbd
    AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
    AuthnCacheProvideFor dbd
    Require valid-user
    #Optional
    AuthnCacheContext dbd-authn-example
</Directory>

Cacheing with custom modules

Module developers should note that their modules must be enabled for cacheing with mod_authn_socache. A single optional API function ap_authn_cache_store is provided to cache credentials a provider has just looked up or generated. Usage examples are available in r957072, in which three authn providers are enabled for cacheing.

AuthnCacheContext Directive

Description: | Specify a context string for use in the cache key
Syntax: | AuthnCacheContext directory|server|custom-string
Default: | directory
Context: | directory
Status: | Base
Module: | mod_authn_socache

This directive specifies a string to be used along with the supplied username (and realm in the case of Digest Authentication) in constructing a cache key. This serves to disambiguate identical usernames serving different authentication areas on the server.

Two special values for this are directory, which uses the directory context of the request as a string, and server which uses the virtual host name.

The default is directory, which is also the most conservative setting. This is likely to be less than optimal, as it (for example) causes $app-base, $app-base/images, $app-base/scripts and $app-base/media each to have its own separate cache key. A better policy is to name the AuthnCacheContext for the password provider: for example a htpasswd file or database table.

Contexts can be shared across different areas of a server, where credentials are shared. However, this has potential to become a vector for cross-site or cross-application security breaches, so this directive is not permitted in .htaccess contexts.

AuthnCacheEnable Directive

Description: | Enable Authn caching configured anywhere
Syntax: | AuthnCacheEnable
Context: | server config
Override: | None
Status: | Base
Module: | mod_authn_socache

This directive is not normally necessary: it is implied if authentication cacheing is enabled anywhere in httpd.conf. However, if it is not enabled anywhere in httpd.conf it will by default not be initialised, and is therefore not available in a .htaccess context. This directive ensures it is initialised so it can be used in .htaccess.

AuthnCacheProvideFor Directive

Description: | Specify which authn provider(s) to cache for
Syntax: | AuthnCacheProvideFor authn-provider [...]
Default: | None
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authn_socache

This directive specifies an authentication provider or providers to cache for. Credentials found by a provider not listed in an AuthnCacheProvideFor directive will not be cached.

For example, to cache credentials found by mod_authn_dbd or by a custom provider myprovider, but leave those looked up by lightweight providers like file or dbm lookup alone:

AuthnCacheProvideFor dbd myprovider

AuthnCacheSOCache Directive

Description: | Select socache backend provider to use
Syntax: | AuthnCacheSOCache provider-name[:provider-args]
Context: | server config
Override: | None
Status: | Base
Module: | mod_authn_socache
Compatibility: | Optional provider arguments are available in Apache HTTP Server 2.4.7 and later

This is a server-wide setting to select a provider for the shared object cache, followed by optional arguments for that provider. Some possible values for provider-name are "dbm", "dc", "memcache", or "shmcb", each subject to the appropriate module being loaded. If not set, your platform's default will be used.

AuthnCacheTimeout Directive

Description: | Set a timeout for cache entries
Syntax: | AuthnCacheTimeout timeout (seconds)
Default: | 300 (5 minutes)
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authn_socache

Cacheing authentication data can be a security issue, though short-term cacheing is unlikely to be a problem. Typically a good solution is to cache credentials for as long as it takes to relieve the load on a backend, but no longer, though if changes to your users and passwords are infrequent then a longer timeout may suit you. The default 300 seconds (5 minutes) is both cautious and ample to keep the load on a backend such as dbd (SQL database queries) down.

This should not be confused with session timeout, which is an entirely separate issue. However, you may wish to check your session-management software for whether cached credentials can "accidentally" extend a session, and bear it in mind when setting your timeout.


mod_authnz_fcgi - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authnz_fcgi

Description: | Allows a FastCGI authorizer application to handle Apache httpd authentication and authorization
Status: | Extension
Module Identifier: | authnz_fcgi_module
Source File: | mod_authnz_fcgi.c
Compatibility: | Available in version 2.4.10 and later

Summary

This module allows FastCGI authorizer applications to authenticate users and authorize access to resources. It supports generic FastCGI authorizers which participate in a single phase for authentication and authorization as well as Apache httpd-specific authenticators and authorizors which participate in one or both phases.

FastCGI authorizers can authenticate using user id and password, such as for Basic authentication, or can authenticate using arbitrary mechanisms.

See also

  • Authentication, Authorization, and Access Control
  • mod_auth_basic
  • fcgistarter
  • mod_proxy_fcgi

Invocation modes

The invocation modes for FastCGI authorizers supported by this module are distinguished by two characteristics, type and auth mechanism.

Type is simply authn for authentication, authz for authorization, or authnz for combined authentication and authorization.

Auth mechanism refers to the Apache httpd configuration mechanisms and processing phases, and can be AuthBasicProvider, Require, or check_user_id. The first two of these correspond to the directives used to enable participation in the appropriate processing phase.

Descriptions of each mode:

Type authn, mechanism AuthBasicProvider
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHENTICATOR. The application must be defined as provider type authn using AuthnzFcgiDefineProvider and enabled with AuthBasicProvider. When invoked, the application is expected to authenticate the client using the provided user id and password. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
        print "Status: 200\n";
        print "Variable-AUTHN_1: authn_01\n";
        print "Variable-AUTHN_2: authn_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/
<Location "/protected/">
  AuthType Basic
  AuthName "Restricted"
  AuthBasicProvider FooAuthn
  Require ...
</Location>
Type authz, mechanism Require
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHORIZER. The application must be defined as provider type authz using AuthnzFcgiDefineProvider. When invoked, the application is expected to authorize the client using the provided user id and other request data. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHORIZER";
    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
    die if $ENV{'REMOTE_PASSWD'};

    print STDERR "This text is written to the web server error log.\n";

    if ($ENV{'REMOTE_USER'} eq "foo1") {
        print "Status: 200\n";
        print "Variable-AUTHZ_1: authz_01\n";
        print "Variable-AUTHZ_2: authz_02\n";
        print "\n";
    }
    else {
        print "Status: 403\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10103/
<Location "/protected/">
  AuthType ...
  AuthName ...
  AuthBasicProvider ...
  Require FooAuthz
</Location>
Type authnz, mechanism AuthBasicProvider + Require
In this mode, which supports the web server-agnostic FastCGI AUTHORIZER protocol, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is not set. The application must be defined as provider type authnz using AuthnzFcgiDefineProvider. The application is expected to handle both authentication and authorization in the same invocation using the user id, password, and other request data. The invocation occurs during the Apache httpd API authentication phase. If the application returns 200 and the same provider is invoked during the authorization phase (via Require), mod_authnz_fcgi will return success for the authorization phase without invoking the application. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'};
    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" &&
        $ENV{'REQUEST_URI'} =~ m%/bar/.*%) {
        print "Status: 200\n";
        print "Variable-AUTHNZ_1: authnz_01\n";
        print "Variable-AUTHNZ_2: authnz_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
<Location "/protected/">
  AuthType Basic
  AuthName "Restricted"
  AuthBasicProvider FooAuthnz
  Require FooAuthnz
</Location>
Type authn, mechanism check_user_id
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHENTICATOR. The application must be defined as provider type authn using AuthnzFcgiDefineProvider. AuthnzFcgiCheckAuthnProvider specifies when it is called. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";

    # This authorizer assumes that the RequireBasicAuth option of
    # AuthnzFcgiCheckAuthnProvider is On:
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
        print "Status: 200\n";
        print "Variable-AUTHNZ_1: authnz_01\n";
        print "Variable-AUTHNZ_2: authnz_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
        # If a response body is written here, it will be returned to
        # the client.
    }
}
Example configuration:
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10103/
<Location "/protected/">
  AuthType ...
  AuthName ...
  AuthnzFcgiCheckAuthnProvider FooAuthn \
                               Authoritative On \
                               RequireBasicAuth Off \
                               UserExpr "%{reqenv:REMOTE_USER}"
  Require ...
</Location>

Additional examples

  1. If your application supports the separate authentication and authorization roles (AUTHENTICATOR and AUTHORIZER), define separate providers as follows, even if they map to the same application:
    AuthnzFcgiDefineProvider authn  FooAuthn  fcgi://localhost:10102/
AuthnzFcgiDefineProvider authz  FooAuthz  fcgi://localhost:10102/
    Specify the authn provider on AuthBasicProvider and the authz provider on Require:
    AuthType Basic
AuthName "Restricted"
AuthBasicProvider FooAuthn
Require FooAuthz
  2. If your application supports the generic AUTHORIZER role (authentication and authorizer in one invocation), define a single provider as follows:
    AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
    Specify the authnz provider on both AuthBasicProvider and Require:
    AuthType Basic
AuthName "Restricted"
AuthBasicProvider FooAuthnz
Require FooAuthnz

Limitations

The following are potential features which are not currently implemented:

Apache httpd access checker
The Apache httpd API access check phase is a separate phase from authentication and authorization. Some other FastCGI implementations implement this phase, which is denoted by the setting of FCGI_APACHE_ROLE to ACCESS_CHECKER.
Local (Unix) sockets or pipes
Only TCP sockets are currently supported.
Support for mod_authn_socache
mod_authn_socache interaction should be implemented for applications which participate in Apache httpd-style authentication.
Support for digest authentication using AuthDigestProvider
This is expected to be a permanent limitation as there is no authorizer flow for retrieving a hash.
Application process management
This is expected to be permanently out of scope for this module. Application processes must be controlled by other means. For example, fcgistarter can be used to start them.
AP_AUTH_INTERNAL_PER_URI
All providers are currently registered as AP_AUTH_INTERNAL_PER_CONF, which means that checks are not performed again for internal subrequests with the same access control configuration as the initial request.
Protocol data charset conversion
If mod_authnz_fcgi runs in an EBCDIC compilation environment, all FastCGI protocol data is written in EBCDIC and expected to be received in EBCDIC.
Multiple requests per connection
Currently the connection to the FastCGI authorizer is closed after every phase of processing. For example, if the authorizer handles separate authn and authz phases then two connections will be used.
URI Mapping
URIs from clients can't be mapped, such as with the ProxyPass used with FastCGI responders.

Logging

  1. Processing errors are logged at log level error and higher.
  2. Messages written by the application are logged at log level warn.
  3. General messages for debugging are logged at log level debug.
  4. Environment variables passed to the application are logged at log level trace2. The value of the REMOTE_PASSWD variable will be obscured, but any other sensitive data will be visible in the log.
  5. All I/O between the module and the FastCGI application, including all environment variables, will be logged in printable and hex format at log level trace5. All sensitive data will be visible in the log.

LogLevel can be used to configure a log level specific to mod_authnz_fcgi. For example:

LogLevel info authnz_fcgi:trace8

AuthnzFcgiCheckAuthnProvider Directive

Description: | Enables a FastCGI application to handle the check_authn authentication hook.
Syntax: | AuthnzFcgiCheckAuthnProvider provider-name|None option ...
Default: | none
Context: | directory
Status: | Extension
Module: | mod_authnz_fcgi

This directive is used to enable a FastCGI authorizer to handle a specific processing phase of authentication or authorization.

Some capabilities of FastCGI authorizers require enablement using this directive instead of AuthBasicProvider:

  • Non-Basic authentication; generally, determining the user id of the client and returning it from the authorizer; see the UserExpr option below
  • Selecting a custom response code; for a non-200 response from the authorizer, the code from the authorizer will be the status of the response
  • Setting the body of a non-200 response; if the authorizer provides a response body with a non-200 response, that body will be returned to the client; up to 8192 bytes of text are supported
provider-name
This is the name of a provider defined with AuthnzFcgiDefineProvider.
None
Specify None to disable a provider enabled with this directive in an outer scope, such as in a parent directory.
option
The following options are supported:
Authoritative On|Off (default On)
This controls whether or not other modules are allowed to run when this module has a FastCGI authorizer configured and it fails the request.
DefaultUser userid
When the authorizer returns success and UserExpr is configured and evaluates to an empty string (e.g., authorizer didn't return a variable), this value will be used as the user id. This is typically used when the authorizer has a concept of guest, or unauthenticated, users and guest users are mapped to some specific user id for logging and other purposes.
RequireBasicAuth On|Off (default Off)
This controls whether or not Basic auth is required before passing the request to the authorizer. If required, the authorizer won't be invoked without a user id and password; 401 will be returned for a request without that.
UserExpr expr (no default)
When Basic authentication isn't provided by the client and the authorizer determines the user, this expression, evaluated after calling the authorizer, determines the user. The expression follows ap_expr syntax and must resolve to a string. A typical use is to reference a Variable-XXX setting returned by the authorizer using an option like UserExpr "%{reqenv:XXX}". If this option is specified and the user id can't be retrieved using the expression after a successful authentication, the request will be rejected with a 500 error.

AuthnzFcgiDefineProvider Directive

Description: | Defines a FastCGI application as a provider for authentication and/or authorization
Syntax: | AuthnzFcgiDefineProvider type provider-name backend-address
Default: | none
Context: | server config
Status: | Extension
Module: | mod_authnz_fcgi

This directive is used to define a FastCGI application as a provider for a particular phase of authentication or authorization.

type
This must be set to authn for authentication, authz for authorization, or authnz for a generic FastCGI authorizer which performs both checks.
provider-name
This is used to assign a name to the provider which is used in other directives such as AuthBasicProvider and Require.
backend-address
This specifies the address of the application, in the form fcgi://hostname:port/. The application process(es) must be managed independently, such as with fcgistarter.


mod_authnz_ldap - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authnz_ldap

Description: | Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
Status: | Extension
Module Identifier: | authnz_ldap_module
Source File: | mod_authnz_ldap.c
Compatibility: | Available in version 2.1 and later

Summary

This module allows authentication front-ends such as mod_auth_basic to authenticate users through an ldap directory.

mod_authnz_ldap supports the following features:

  • Known to support the OpenLDAP SDK (both 1.x and 2.x), Novell LDAP SDK and the iPlanet (Netscape) SDK.
  • Complex authorization policies can be implemented by representing the policy with LDAP filters.
  • Uses extensive caching of LDAP operations via mod_ldap.
  • Support for LDAP over SSL (requires the Netscape SDK) or TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).

When using mod_auth_basic, this module is invoked via the AuthBasicProvider directive with the ldap value.

See also

  • mod_ldap
  • mod_auth_basic
  • mod_authz_user
  • mod_authz_groupfile

Contents

  • General caveats
  • Operation
    • The Authentication Phase
    • The Authorization Phase
  • The Require Directives
    • Require ldap-user
    • Require ldap-group
    • Require ldap-dn
    • Require ldap-attribute
    • Require ldap-filter
  • Examples
  • Using TLS
  • Using SSL
  • Exposing Login Information
  • Using Active Directory
  • Using Microsoft FrontPage with mod_authnz_ldap
    • How It Works
    • Caveats

General caveats

This module caches authentication and authorization results based on the configuration of mod_ldap. Changes made to the backing LDAP server will not be immediately reflected on the HTTP Server, including but not limited to user lockouts/revocations, password changes, or changes to group memberships. Consult the directives in mod_ldap for details of the cache tunables.

Operation

There are two phases in granting access to a user. The first phase is authentication, in which the mod_authnz_ldap authentication provider verifies that the user's credentials are valid. This is also called the search/bind phase. The second phase is authorization, in which mod_authnz_ldap determines if the authenticated user is allowed access to the resource in question. This is also known as the compare phase.

mod_authnz_ldap registers both an authn_ldap authentication provider and an authz_ldap authorization handler. The authn_ldap authentication provider can be enabled through the AuthBasicProvider directive using the ldap value. The authz_ldap handler extends the Require directive's authorization types by adding ldap-user, ldap-dn and ldap-group values.

The Authentication Phase

During the authentication phase, mod_authnz_ldap searches for an entry in the directory that matches the username that the HTTP client passes. If a single unique match is found, then mod_authnz_ldap attempts to bind to the directory server using the DN of the entry plus the password provided by the HTTP client. Because it does a search, then a bind, it is often referred to as the search/bind phase. Here are the steps taken during the search/bind phase.

  1. Generate a search filter by combining the attribute and filter provided in the AuthLDAPURL directive with the username passed by the HTTP client.
  2. Search the directory using the generated filter. If the search does not return exactly one entry, deny or decline access.
  3. Fetch the distinguished name of the entry retrieved from the search and attempt to bind to the LDAP server using that DN and the password passed by the HTTP client. If the bind is unsuccessful, deny or decline access.

The following directives are used during the search/bind phase

AuthLDAPURL | Specifies the LDAP server, the base DN, the attribute to use in the search, as well as the extra search filter to use.
AuthLDAPBindDN | An optional DN to bind with during the search phase.
AuthLDAPBindPassword | An optional password to bind with during the search phase.

The Authorization Phase

During the authorization phase, mod_authnz_ldap attempts to determine if the user is authorized to access the resource. Many of these checks require mod_authnz_ldap to do a compare operation on the LDAP server. This is why this phase is often referred to as the compare phase. mod_authnz_ldap accepts the following Require directives to determine if the credentials are acceptable:

  • Grant access if there is a Require ldap-user directive, and the username in the directive matches the username passed by the client.
  • Grant access if there is a Require ldap-dn directive, and the DN in the directive matches the DN fetched from the LDAP directory.
  • Grant access if there is a Require ldap-group directive, and the DN fetched from the LDAP directory (or the username passed by the client) occurs in the LDAP group or, potentially, in one of its sub-groups.
  • Grant access if there is a Require ldap-attribute directive, and the attribute fetched from the LDAP directory matches the given value.
  • Grant access if there is a Require ldap-filter directive, and the search filter successfully finds a single user object that matches the dn of the authenticated user.
  • otherwise, deny or decline access

Other Require values may also be used which may require loading additional authorization modules.

  • Grant access to all successfully authenticated users if there is a Require valid-user directive. (requires mod_authz_user)
  • Grant access if there is a Require group directive, and mod_authz_groupfile has been loaded with the AuthGroupFile directive set.
  • others...

mod_authnz_ldap uses the following directives during the compare phase:

AuthLDAPURL | The attribute specified in the URL is used in compare operations for the Require ldap-user operation.
AuthLDAPCompareDNOnServer | Determines the behavior of the Require ldap-dn directive.
AuthLDAPGroupAttribute | Determines the attribute to use for comparisons in the Require ldap-group directive.
AuthLDAPGroupAttributeIsDN | Specifies whether to use the user DN or the username when doing comparisons for the Require ldap-group directive.
AuthLDAPMaxSubGroupDepth | Determines the maximum depth of sub-groups that will be evaluated during comparisons in the Require ldap-group directive.
AuthLDAPSubGroupAttribute | Determines the attribute to use when obtaining sub-group members of the current group during comparisons in the Require ldap-group directive.
AuthLDAPSubGroupClass | Specifies the LDAP objectClass values used to identify if queried directory objects really are group objects (as opposed to user objects) during the Require ldap-group directive's sub-group processing.

The Require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authnz_ldap extends the authorization types with ldap-user, ldap-dn, ldap-group, ldap-attribute and ldap-filter. Other authorization types may also be used but may require that additional authorization modules be loaded.

Since v2.4.8, expressions are supported within the LDAP require directives.

Require ldap-user

The Require ldap-user directive specifies what usernames can access the resource. Once mod_authnz_ldap has retrieved a unique DN from the directory, it does an LDAP compare operation using the username specified in the Require ldap-user to see if that username is part of the just-fetched LDAP entry. Multiple users can be granted access by putting multiple usernames on the line, separated with spaces. If a username has a space in it, then it must be surrounded with double quotes. Multiple users can also be granted access by using multiple Require ldap-user directives, with one user per line. For example, with a AuthLDAPURL of ldap://ldap/o=Example?cn (i.e., cn is used for searches), the following Require directives could be used to restrict access:

Require ldap-user "Barbara Jenson"
Require ldap-user "Fred User"
Require ldap-user "Joe Manager"

Because of the way that mod_authnz_ldap handles this directive, Barbara Jenson could sign on as Barbara Jenson, Babs Jenson or any other cn that she has in her LDAP entry. Only the single Require ldap-user line is needed to support all values of the attribute in the user's entry.

If the uid attribute was used instead of the cn attribute in the URL above, the above three lines could be condensed to

Require ldap-user bjenson fuser jmanager

Require ldap-group

This directive specifies an LDAP group whose members are allowed access. It takes the distinguished name of the LDAP group. Note: Do not surround the group name with quotes. For example, assume that the following entry existed in the LDAP directory:

dn: cn=Administrators, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Example
uniqueMember: cn=Fred User, o=Example

The following directive would grant access to both Fred and Barbara:

Require ldap-group cn=Administrators, o=Example

Members can also be found within sub-groups of a specified LDAP group if AuthLDAPMaxSubGroupDepth is set to a value greater than 0. For example, assume the following entries exist in the LDAP directory:

dn: cn=Employees, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Managers, o=Example
uniqueMember: cn=Administrators, o=Example
uniqueMember: cn=Users, o=Example

dn: cn=Managers, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Bob Ellis, o=Example
uniqueMember: cn=Tom Jackson, o=Example

dn: cn=Administrators, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Example
uniqueMember: cn=Fred User, o=Example

dn: cn=Users, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Allan Jefferson, o=Example
uniqueMember: cn=Paul Tilley, o=Example
uniqueMember: cn=Temporary Employees, o=Example

dn: cn=Temporary Employees, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Jim Swenson, o=Example
uniqueMember: cn=Elliot Rhodes, o=Example

The following directives would allow access for Bob Ellis, Tom Jackson, Barbara Jenson, Fred User, Allan Jefferson, and Paul Tilley but would not allow access for Jim Swenson, or Elliot Rhodes (since they are at a sub-group depth of 2):

Require ldap-group cn=Employees, o=Example
AuthLDAPMaxSubGroupDepth 1

Behavior of this directive is modified by the AuthLDAPGroupAttribute, AuthLDAPGroupAttributeIsDN, AuthLDAPMaxSubGroupDepth, AuthLDAPSubGroupAttribute, and AuthLDAPSubGroupClass directives.

Require ldap-dn

The Require ldap-dn directive allows the administrator to grant access based on distinguished names. It specifies a DN that must match for access to be granted. If the distinguished name that was retrieved from the directory server matches the distinguished name in the Require ldap-dn, then authorization is granted. Note: do not surround the distinguished name with quotes.

The following directive would grant access to a specific DN:

Require ldap-dn cn=Barbara Jenson, o=Example

Behavior of this directive is modified by the AuthLDAPCompareDNOnServer directive.

Require ldap-attribute

The Require ldap-attribute directive allows the administrator to grant access based on attributes of the authenticated user in the LDAP directory. If the attribute in the directory matches the value given in the configuration, access is granted.

The following directive would grant access to anyone with the attribute employeeType = active

Require ldap-attribute "employeeType=active"

Multiple attribute/value pairs can be specified on the same line separated by spaces or they can be specified in multiple Require ldap-attribute directives. The effect of listing multiple attribute/values pairs is an OR operation. Access will be granted if any of the listed attribute values match the value of the corresponding attribute in the user object. If the value of the attribute contains a space, only the value must be within double quotes.

The following directive would grant access to anyone with the city attribute equal to "San Jose" or status equal to "Active"

Require ldap-attribute city="San Jose" "status=active"

Require ldap-filter

The Require ldap-filter directive allows the administrator to grant access based on a complex LDAP search filter. If the dn returned by the filter search matches the authenticated user dn, access is granted.

The following directive would grant access to anyone having a cell phone and is in the marketing department

Require ldap-filter "&(cell=*)(department=marketing)"

The difference between the Require ldap-filter directive and the Require ldap-attribute directive is that ldap-filter performs a search operation on the LDAP directory using the specified search filter rather than a simple attribute comparison. If a simple attribute comparison is all that is required, the comparison operation performed by ldap-attribute will be faster than the search operation used by ldap-filter especially within a large directory.

Examples

  • Grant access to anyone who exists in the LDAP directory, using their UID for searches.
    AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"
Require valid-user
  • The next example is the same as above; but with the fields that have useful defaults omitted. Also, note the use of a redundant LDAP server.
    AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"
Require valid-user
  • The next example is similar to the previous one, but it uses the common name instead of the UID. Note that this could be problematical if multiple people in the directory share the same cn, because a search on cn must return exactly one entry. That's why this approach is not recommended: it's a better idea to choose an attribute that is guaranteed unique in your directory, such as uid.
    AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"
Require valid-user
  • Grant access to anybody in the Administrators group. The users must authenticate using their UID.
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid
Require ldap-group cn=Administrators, o=Example
  • Grant access to anybody in the group whose name matches the hostname of the virtual host. In this example an expression is used to build the filter.
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid
Require ldap-group cn=%{SERVER_NAME}, o=Example
  • The next example assumes that everyone at Example who carries an alphanumeric pager will have an LDAP attribute of qpagePagerID. The example will grant access only to people (authenticated via their UID) who have alphanumeric pagers:
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)
Require valid-user

  • The next example demonstrates the power of using filters to accomplish complicated administrative requirements. Without filters, it would have been necessary to create a new LDAP group and ensure that the group's members remain synchronized with the pager users. This becomes trivial with filters. The goal is to grant access to anyone who has a pager, plus grant access to Joe Manager, who doesn't have a pager, but does need to access the same resource:

    AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(|(qpagePagerID=*)(uid=jmanager))
Require valid-user

    This last may look confusing at first, so it helps to evaluate what the search filter will look like based on who connects, as shown below. If Fred User connects as fuser, the filter would look like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

    The above search will only succeed if fuser has a pager. When Joe Manager connects as jmanager, the filter looks like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

    The above search will succeed whether jmanager has a pager or not.

Using TLS

To use TLS, see the mod_ldap directives LDAPTrustedClientCert, LDAPTrustedGlobalCert and LDAPTrustedMode.

An optional second parameter can be added to the AuthLDAPURL to override the default connection type set by LDAPTrustedMode. This will allow the connection established by an ldap:// Url to be upgraded to a secure connection on the same port.

Using SSL

To use SSL, see the mod_ldap directives LDAPTrustedClientCert, LDAPTrustedGlobalCert and LDAPTrustedMode.

To specify a secure LDAP server, use ldaps:// in the AuthLDAPURL directive, instead of ldap://.

Exposing Login Information

when this module performs authentication, ldap attributes specified in the authldapurl directive are placed in environment variables with the prefix "AUTHENTICATE_".

when this module performs authorization, ldap attributes specified in the authldapurl directive are placed in environment variables with the prefix "AUTHORIZE_".

If the attribute field contains the username, common name and telephone number of a user, a CGI program will have access to this information without the need to make a second independent LDAP query to gather this additional information.

This has the potential to dramatically simplify the coding and configuration required in some web applications.

Using Active Directory

An Active Directory installation may support multiple domains at the same time. To distinguish users between domains, an identifier called a User Principle Name (UPN) can be added to a user's entry in the directory. This UPN usually takes the form of the user's account name, followed by the domain components of the particular domain, for example somebody@nz.example.com.

You may wish to configure the mod_authnz_ldap module to authenticate users present in any of the domains making up the Active Directory forest. In this way both somebody@nz.example.com and someone@au.example.com can be authenticated using the same query at the same time.

To make this practical, Active Directory supports the concept of a Global Catalog. This Global Catalog is a read only copy of selected attributes of all the Active Directory servers within the Active Directory forest. Querying the Global Catalog allows all the domains to be queried in a single query, without the query spanning servers over potentially slow links.

If enabled, the Global Catalog is an independent directory server that runs on port 3268 (3269 for SSL). To search for a user, do a subtree search for the attribute userPrincipalName, with an empty search root, like so:

AuthLDAPBindDN apache@example.com
AuthLDAPBindPassword password
AuthLDAPURL ldap://10.0.0.1:3268/?userPrincipalName?sub

Users will need to enter their User Principal Name as a login, in the form somebody@nz.example.com.

Using Microsoft FrontPage with mod_authnz_ldap

Normally, FrontPage uses FrontPage-web-specific user/group files (i.e., the mod_authn_file and mod_authz_groupfile modules) to handle all authentication. Unfortunately, it is not possible to just change to LDAP authentication by adding the proper directives, because it will break the Permissions forms in the FrontPage client, which attempt to modify the standard text-based authorization files.

Once a FrontPage web has been created, adding LDAP authentication to it is a matter of adding the following directives to every .htaccess file that gets created in the web

AuthLDAPURL       "the url"
AuthGroupFile     "mygroupfile"
Require group     "mygroupfile"

How It Works

FrontPage restricts access to a web by adding the Require valid-user directive to the .htaccess files. The Require valid-user directive will succeed for any user who is valid as far as LDAP is concerned. This means that anybody who has an entry in the LDAP directory is considered a valid user, whereas FrontPage considers only those people in the local user file to be valid. By substituting the ldap-group with group file authorization, Apache is allowed to consult the local user file (which is managed by FrontPage) - instead of LDAP - when handling authorizing the user.

Once directives have been added as specified above, FrontPage users will be able to perform all management operations from the FrontPage client.

Caveats

  • When choosing the LDAP URL, the attribute to use for authentication should be something that will also be valid for putting into a mod_authn_file user file. The user ID is ideal for this.
  • When adding users via FrontPage, FrontPage administrators should choose usernames that already exist in the LDAP directory (for obvious reasons). Also, the password that the administrator enters into the form is ignored, since Apache will actually be authenticating against the password in the LDAP database, and not against the password in the local user file. This could cause confusion for web administrators.
  • Apache must be compiled with mod_auth_basic, mod_authn_file and mod_authz_groupfile in order to use FrontPage support. This is because Apache will still use the mod_authz_groupfile group file for determine the extent of a user's access to the FrontPage web.
  • The directives must be put in the .htaccess files. Attempting to put them inside <Location> or <Directory> directives won't work. This is because mod_authnz_ldap has to be able to grab the AuthGroupFile directive that is found in FrontPage .htaccess files so that it knows where to look for the valid user list. If the mod_authnz_ldap directives aren't in the same .htaccess file as the FrontPage directives, then the hack won't work, because mod_authnz_ldap will never get a chance to process the .htaccess file, and won't be able to find the FrontPage-managed user file.

AuthLDAPAuthorizePrefix Directive

Description: | Specifies the prefix for environment variables set during authorization
Syntax: | AuthLDAPAuthorizePrefix prefix
Default: | AuthLDAPAuthorizePrefix AUTHORIZE_
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.6 and later

This directive allows you to override the prefix used for environment variables set during LDAP authorization. If AUTHENTICATE_ is specified, consumers of these environment variables see the same information whether LDAP has performed authentication, authorization, or both.

Note

No authorization variables are set when a user is authorized on the basis of Require valid-user.

AuthLDAPBindAuthoritative Directive

Description: | Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
Syntax: | AuthLDAPBindAuthoritative off|on
Default: | AuthLDAPBindAuthoritative on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

By default, subsequent authentication providers are only queried if a user cannot be mapped to a DN, but not if the user can be mapped to a DN and their password cannot be verified with an LDAP bind. If AuthLDAPBindAuthoritative is set to off, other configured authentication modules will have a chance to validate the user if the LDAP bind (with the current user's credentials) fails for any reason.

This allows users present in both LDAP and AuthUserFile to authenticate when the LDAP server is available but the user's account is locked or password is otherwise unusable.

See also

  • AuthUserFile
  • AuthBasicProvider

AuthLDAPBindDN Directive

Description: | Optional DN to use in binding to the LDAP server
Syntax: | AuthLDAPBindDN distinguished-name
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

An optional DN used to bind to the server when searching for entries. If not provided, mod_authnz_ldap will use an anonymous bind.

AuthLDAPBindPassword Directive

Description: | Password used in conjuction with the bind DN
Syntax: | AuthLDAPBindPassword password
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | exec: was added in 2.4.5.

A bind password to use in conjunction with the bind DN. Note that the bind password is probably sensitive data, and should be properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword if you absolutely need them to search the directory.

If the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the password.

#Password used as-is
AuthLDAPBindPassword secret

#Run /path/to/program to get my password
AuthLDAPBindPassword exec:/path/to/program

#Run /path/to/otherProgram and provide arguments
AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"

AuthLDAPCharsetConfig Directive

Description: | Language to charset conversion configuration file
Syntax: | AuthLDAPCharsetConfig file-path
Context: | server config
Status: | Extension
Module: | mod_authnz_ldap

The AuthLDAPCharsetConfig directive sets the location of the language to charset conversion configuration file. File-path is relative to the ServerRoot. This file specifies the list of language extensions to character sets. Most administrators use the provided charset.conv file, which associates common language extensions to character sets.

The file contains lines in the following format:

Language-Extension charset [Language-String] ...

The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#) are ignored.

AuthLDAPCompareAsUser Directive

Description: | Use the authenticated user's credentials to perform authorization comparisons
Syntax: | AuthLDAPCompareAsUser on|off
Default: | AuthLDAPCompareAsUser off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.6 and later

When set, and mod_authnz_ldap has authenticated the user, LDAP comparisons for authorization use the queried distinguished name (DN) and HTTP basic authentication password of the authenticated user instead of the servers configured credentials.

The ldap-attribute, ldap-user, and ldap-group (single-level only) authorization checks use comparisons.

This directive only has effect on the comparisons performed during nested group processing when AuthLDAPSearchAsUser is also enabled.

This directive should only be used when your LDAP server doesn't accept anonymous comparisons and you cannot use a dedicated AuthLDAPBindDN.

See also

  • AuthLDAPInitialBindAsUser
  • AuthLDAPSearchAsUser

AuthLDAPCompareDNOnServer Directive

Description: | Use the LDAP server to compare the DNs
Syntax: | AuthLDAPCompareDNOnServer on|off
Default: | AuthLDAPCompareDNOnServer on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

When set, mod_authnz_ldap will use the LDAP server to compare the DNs. This is the only foolproof way to compare DNs. mod_authnz_ldap will search the directory for the DN specified with the Require dn directive, then, retrieve the DN and compare it with the DN retrieved from the user entry. If this directive is not set, mod_authnz_ldap simply does a string comparison. It is possible to get false negatives with this approach, but it is much faster. Note the mod_ldap cache can speed up DN comparison in most situations.

AuthLDAPDereferenceAliases Directive

Description: | When will the module de-reference aliases
Syntax: | AuthLDAPDereferenceAliases never|searching|finding|always
Default: | AuthLDAPDereferenceAliases always
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

This directive specifies when mod_authnz_ldap will de-reference aliases during LDAP operations. The default is always.

AuthLDAPGroupAttribute Directive

Description: | LDAP attributes used to identify the user members of groups.
Syntax: | AuthLDAPGroupAttribute attribute
Default: | AuthLDAPGroupAttribute member uniquemember
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

This directive specifies which LDAP attributes are used to check for user members within groups. Multiple attributes can be used by specifying this directive multiple times. If not specified, then mod_authnz_ldap uses the member and uniquemember attributes.

AuthLDAPGroupAttributeIsDN Directive

Description: | Use the DN of the client username when checking for group membership
Syntax: | AuthLDAPGroupAttributeIsDN on|off
Default: | AuthLDAPGroupAttributeIsDN on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

When set on, this directive says to use the distinguished name of the client username when checking for group membership. Otherwise, the username will be used. For example, assume that the client sent the username bjenson, which corresponds to the LDAP DN cn=Babs Jenson, o=Example. If this directive is set, mod_authnz_ldap will check if the group has cn=Babs Jenson, o=Example as a member. If this directive is not set, then mod_authnz_ldap will check if the group has bjenson as a member.

AuthLDAPInitialBindAsUser Directive

Description: | Determines if the server does the initial DN lookup using the basic authentication users' own username, instead of anonymously or with hard-coded credentials for the server
Syntax: | AuthLDAPInitialBindAsUser off|on
Default: | AuthLDAPInitialBindAsUser off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.6 and later

By default, the server either anonymously, or with a dedicated user and password, converts the basic authentication username into an LDAP distinguished name (DN). This directive forces the server to use the verbatim username and password provided by the incoming user to perform the initial DN search.

If the verbatim username can't directly bind, but needs some cosmetic transformation, see AuthLDAPInitialBindPattern.

This directive should only be used when your LDAP server doesn't accept anonymous searches and you cannot use a dedicated AuthLDAPBindDN.

Not available with authorization-only

This directive can only be used if this module authenticates the user, and has no effect when this module is used exclusively for authorization.

See also

  • AuthLDAPInitialBindPattern
  • AuthLDAPBindDN
  • AuthLDAPCompareAsUser
  • AuthLDAPSearchAsUser

AuthLDAPInitialBindPattern Directive

Description: | Specifies the transformation of the basic authentication username to be used when binding to the LDAP server to perform a DN lookup
Syntax: | AuthLDAPInitialBindPattern regex substitution
Default: | AuthLDAPInitialBindPattern (.*) $1 (remote username used verbatim)
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.6 and later

If AuthLDAPInitialBindAsUser is set to ON, the basic authentication username will be transformed according to the regular expression and substitution arguments.

The regular expression argument is compared against the current basic authentication username. The substitution argument may contain backreferences, but has no other variable interpolation.

This directive should only be used when your LDAP server doesn't accept anonymous searches and you cannot use a dedicated AuthLDAPBindDN.

AuthLDAPInitialBindPattern (.+) $1@example.com
AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com

Not available with authorization-only

This directive can only be used if this module authenticates the user, and has no effect when this module is used exclusively for authorization.

debugging

The substituted DN is recorded in the environment variable LDAP_BINDASUSER. If the regular expression does not match the input, the verbatim username is used.

See also

  • AuthLDAPInitialBindAsUser
  • AuthLDAPBindDN

AuthLDAPMaxSubGroupDepth Directive

Description: | Specifies the maximum sub-group nesting depth that will be evaluated before the user search is discontinued.
Syntax: | AuthLDAPMaxSubGroupDepth Number
Default: | AuthLDAPMaxSubGroupDepth 10
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.0 and later

When this directive is set to a non-zero value X combined with use of the Require ldap-group someGroupDN directive, the provided user credentials will be searched for as a member of the someGroupDN directory object or of any group member of the current group up to the maximum nesting level X specified by this directive.

See the Require ldap-group section for a more detailed example.

Nested groups performance

When AuthLDAPSubGroupAttribute overlaps with AuthLDAPGroupAttribute (as it does by default and as required by common LDAP schemas), uncached searching for subgroups in large groups can be very slow. If you use large, non-nested groups, set AuthLDAPMaxSubGroupDepth to zero.

AuthLDAPRemoteUserAttribute Directive

Description: | Use the value of the attribute returned during the user query to set the REMOTE_USER environment variable
Syntax: | AuthLDAPRemoteUserAttribute uid
Default: | none
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

If this directive is set, the value of the REMOTE_USER environment variable will be set to the value of the attribute specified. Make sure that this attribute is included in the list of attributes in the AuthLDAPUrl definition, otherwise this directive will have no effect. This directive, if present, takes precedence over AuthLDAPRemoteUserIsDN. This directive is useful should you want people to log into a website using an email address, but a backend application expects the username as a userid.

AuthLDAPRemoteUserIsDN Directive

Description: | Use the DN of the client username to set the REMOTE_USER environment variable
Syntax: | AuthLDAPRemoteUserIsDN on|off
Default: | AuthLDAPRemoteUserIsDN off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

If this directive is set to on, the value of the REMOTE_USER environment variable will be set to the full distinguished name of the authenticated user, rather than just the username that was passed by the client. It is turned off by default.

AuthLDAPSearchAsUser Directive

Description: | Use the authenticated user's credentials to perform authorization searches
Syntax: | AuthLDAPSearchAsUser on|off
Default: | AuthLDAPSearchAsUser off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.6 and later

When set, and mod_authnz_ldap has authenticated the user, LDAP searches for authorization use the queried distinguished name (DN) and HTTP basic authentication password of the authenticated user instead of the servers configured credentials.

The ldap-filter and ldap-dn authorization checks use searches.

This directive only has effect on the comparisons performed during nested group processing when AuthLDAPCompareAsUser is also enabled.

This directive should only be used when your LDAP server doesn't accept anonymous searches and you cannot use a dedicated AuthLDAPBindDN.

See also

  • AuthLDAPInitialBindAsUser
  • AuthLDAPCompareAsUser

AuthLDAPSubGroupAttribute Directive

Description: | Specifies the attribute labels, one value per directive line, used to distinguish the members of the current group that are groups.
Syntax: | AuthLDAPSubGroupAttribute attribute
Default: | AuthLDAPSubgroupAttribute member uniquemember
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.0 and later

An LDAP group object may contain members that are users and members that are groups (called nested or sub groups). The AuthLDAPSubGroupAttribute directive identifies the labels of group members and the AuthLDAPGroupAttribute directive identifies the labels of the user members. Multiple attributes can be used by specifying this directive multiple times. If not specified, then mod_authnz_ldap uses the member and uniqueMember attributes.

AuthLDAPSubGroupClass Directive

Description: | Specifies which LDAP objectClass values identify directory objects that are groups during sub-group processing.
Syntax: | AuthLDAPSubGroupClass LdapObjectClass
Default: | AuthLDAPSubGroupClass groupOfNames groupOfUniqueNames
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in version 2.3.0 and later

An LDAP group object may contain members that are users and members that are groups (called nested or sub groups). The AuthLDAPSubGroupAttribute directive identifies the labels of members that may be sub-groups of the current group (as opposed to user members). The AuthLDAPSubGroupClass directive specifies the LDAP objectClass values used in verifying that these potential sub-groups are in fact group objects. Verified sub-groups can then be searched for more user or sub-group members. Multiple attributes can be used by specifying this directive multiple times. If not specified, then mod_authnz_ldap uses the groupOfNames and groupOfUniqueNames values.

AuthLDAPUrl Directive

Description: | URL specifying the LDAP search parameters
Syntax: | AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS]
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

An RFC 2255 URL which specifies the LDAP search parameters to use. The syntax of the URL is

ldap://host:port/basedn?attribute?scope?filter

If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:

AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."

Caveat: If you specify multiple servers, you need to enclose the entire URL string in quotes; otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." You can of course use search parameters on each of these.

ldap
For regular ldap, use the string ldap. For secure LDAP, use ldaps instead. Secure LDAP is only available if Apache was linked to an LDAP library with SSL support.
host:port

The name/port of the ldap server (defaults to localhost:389 for ldap, and localhost:636 for ldaps). To specify multiple, redundant LDAP servers, just list all servers, separated by spaces. mod_authnz_ldap will try connecting to each server in turn, until it makes a successful connection. If multiple ldap servers are specified, then entire LDAP URL must be encapsulated in double quotes.

Once a connection has been made to a server, that connection remains active for the life of the httpd process, or until the LDAP server goes down.

If the LDAP server goes down and breaks an existing connection, mod_authnz_ldap will attempt to re-connect, starting with the primary server, and trying each redundant server in turn. Note that this is different than a true round-robin search.

basedn
The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but could also specify a subtree in the directory.
attribute
The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using. All attributes listed will be put into the environment with an AUTHENTICATE_ prefix for use by other modules.
scope
The scope of the search. Can be either one or sub. Note that a scope of base is also supported by RFC 2255, but is not supported by this module. If the scope is not provided, or if base scope is specified, the default is to use a scope of sub.
filter
A valid LDAP search filter. If not provided, defaults to (objectClass=*), which will search for all objects in the tree. Filters are limited to approximately 8000 characters (the definition of MAX_STRING_LEN in the Apache source code). This should be more than sufficient for any application. In 2.4.10 and later, the keyword none disables the use of a filter; this is required by some primitive LDAP servers.

When doing searches, the attribute, filter and username passed by the HTTP client are combined to create a search filter that looks like (&(filter)(attribute=username)).

For example, consider an URL of ldap://ldap.example.com/o=Example?cn?sub?(posixid=*). When a client attempts to connect using a username of Babs Jenson, the resulting search filter will be (&(posixid=*)(cn=Babs Jenson)).

An optional parameter can be added to allow the LDAP Url to override the connection type. This parameter can be one of the following:

NONE
Establish an unsecure connection on the default LDAP port. This is the same as ldap:// on port 389.
SSL
Establish a secure connection on the default secure LDAP port. This is the same as ldaps://
TLS | STARTTLS
Establish an upgraded secure connection on the default LDAP port. This connection will be initiated on port 389 by default and then upgraded to a secure connection on the same port.

See above for examples of AuthLDAPUrl URLs.


mod_authz_core - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_core

Description: | Core Authorization
Status: | Base
Module Identifier: | authz_core_module
Source File: | mod_authz_core.c
Compatibility: | Available in Apache HTTPD 2.3 and later

Summary

This module provides core authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site. mod_authz_core provides the functionality to register various authorization providers. It is usually used in conjunction with an authentication provider module such as mod_authn_file and an authorization module such as mod_authz_user. It also allows for advanced logic to be applied to the authorization processing.

Creating Authorization Provider Aliases

Extended authorization providers can be created within the configuration file and assigned an alias name. The alias providers can then be referenced through the Require directive in the same way as a base authorization provider. Besides the ability to create and alias an extended provider, it also allows the same extended authorization provider to be referenced by multiple locations.

Example

The example below creates two different ldap authorization provider aliases based on the ldap-group authorization provider. This example allows a single authorization location to check group membership within multiple ldap hosts:

<AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
    AuthLDAPBindDN cn=youruser,o=ctx
    AuthLDAPBindPassword yourpassword
    AuthLDAPURL ldap://ldap.host/o=ctx
</AuthzProviderAlias>

<AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
    AuthLDAPBindDN cn=yourotheruser,o=dev
    AuthLDAPBindPassword yourotherpassword
    AuthLDAPURL ldap://other.ldap.host/o=dev?cn
</AuthzProviderAlias>

Alias "/secure" "/webpages/secure"
<Directory "/webpages/secure">
    Require all granted

    AuthBasicProvider file

    AuthType Basic
    AuthName LDAP_Protected_Place

    #implied OR operation
    Require ldap-group-alias1
    Require ldap-group-alias2
</Directory>

Authorization Containers

The authorization container directives <RequireAll>, <RequireAny> and <RequireNone> may be combined with each other and with the Require directive to express complex authorization logic.

The example below expresses the following authorization logic. In order to access the resource, the user must either be the superadmin user, or belong to both the admins group and the Administrators LDAP group and either belong to the sales group or have the LDAP dept attribute sales. Furthermore, in order to access the resource, the user must not belong to either the temps group or the LDAP group Temporary Employees.

<Directory "/www/mydocs">
    <RequireAll>
        <RequireAny>
            Require user superadmin
            <RequireAll>
                Require group admins
                Require ldap-group cn=Administrators,o=Airius
                <RequireAny>
                    Require group sales
                    Require ldap-attribute dept="sales"
                </RequireAny>
            </RequireAll>
        </RequireAny>
        <RequireNone>
            Require group temps
            Require ldap-group cn=Temporary Employees,o=Airius
        </RequireNone>
    </RequireAll>
</Directory>

The Require Directives

mod_authz_core provides some generic authorization providers which can be used with the Require directive.

Require env

The env provider allows access to the server to be controlled based on the existence of an environment variable. When Require env env-variable is specified, then the request is allowed access if the environment variable env-variable exists. The server provides the ability to set environment variables in a flexible way based on characteristics of the client request using the directives provided by mod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clients User-Agent (browser type), Referer, or other HTTP request header fields.

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory "/docroot">
    Require env let_me_in
</Directory>

In this case, browsers with a user-agent string beginning with KnockKnock/2.0 will be allowed access, and all others will be denied.

When the server looks up a path via an internal subrequest such as looking for a DirectoryIndex or generating a directory listing with mod_autoindex, per-request environment variables are not inherited in the subrequest. Additionally, SetEnvIf directives are not separately evaluated in the subrequest due to the API phases mod_setenvif takes action in.

Require all

The all provider mimics the functionality that was previously provided by the 'Allow from all' and 'Deny from all' directives. This provider can take one of two arguments which are 'granted' or 'denied'. The following examples will grant or deny access to all requests.

Require all granted
Require all denied

Require method

The method provider allows using the HTTP method in authorization decisions. The GET and HEAD methods are treated as equivalent. The TRACE method is not available to this provider, use TraceEnable instead.

The following example will only allow GET, HEAD, POST, and OPTIONS requests:

Require method GET POST OPTIONS

The following example will allow GET, HEAD, POST, and OPTIONS requests without authentication, and require a valid user for all other methods:

<RequireAny>
     Require method GET POST OPTIONS
     Require valid-user
</RequireAny>

Require expr

The expr provider allows basing authorization decisions on arbitrary expressions.

Require expr "%{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17"
<RequireAll>
    Require expr "!(%{QUERY_STRING} =~ /secret/)"
    Require expr "%{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"
</RequireAll>
Require expr "!(%{QUERY_STRING} =~ /secret/) && %{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"

The syntax is described in the ap_expr documentation.

Normally, the expression is evaluated before authentication. However, if the expression returns false and references the variable %{REMOTE_USER}, authentication will be performed and the expression will be re-evaluated.

AuthMerging Directive

Description: | Controls the manner in which each configuration section's authorization logic is combined with that of preceding configuration sections.
Syntax: | AuthMerging Off | And | Or
Default: | AuthMerging Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_core

When authorization is enabled, it is normally inherited by each subsequent configuration section, unless a different set of authorization directives is specified. This is the default action, which corresponds to an explicit setting of AuthMerging Off.

However, there may be circumstances in which it is desirable for a configuration section's authorization to be combined with that of its predecessor while configuration sections are being merged. Two options are available for this case, And and Or.

When a configuration section contains AuthMerging And or AuthMerging Or, its authorization logic is combined with that of the nearest predecessor (according to the overall order of configuration sections) which also contains authorization logic as if the two sections were jointly contained within a <RequireAll> or <RequireAny> directive, respectively.

The setting of AuthMerging is not inherited outside of the configuration section in which it appears. In the following example, only users belonging to group alpha may access /www/docs. Users belonging to either groups alpha or beta may access /www/docs/ab. However, the default Off setting of AuthMerging applies to the <Directory> configuration section for /www/docs/ab/gamma, so that section's authorization directives override those of the preceding sections. Thus only users belong to the group gamma may access /www/docs/ab/gamma.
<Directory "/www/docs">
    AuthType Basic
    AuthName Documents
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    Require group alpha
</Directory>

<Directory "/www/docs/ab">
    AuthMerging Or
    Require group beta
</Directory>

<Directory "/www/docs/ab/gamma">
    Require group gamma
</Directory>

<AuthzProviderAlias> Directive

Description: | Enclose a group of directives that represent an extension of a base authorization provider and referenced by the specified alias
Syntax: | <AuthzProviderAlias baseProvider Alias Require-Parameters> ... </AuthzProviderAlias>
Context: | server config
Status: | Base
Module: | mod_authz_core

<AuthzProviderAlias> and </AuthzProviderAlias> are used to enclose a group of authorization directives that can be referenced by the alias name using the directive Require.

AuthzSendForbiddenOnFailure Directive

Description: | Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if authentication succeeds but authorization fails
Syntax: | AuthzSendForbiddenOnFailure On|Off
Default: | AuthzSendForbiddenOnFailure Off
Context: | directory, .htaccess
Status: | Base
Module: | mod_authz_core
Compatibility: | Available in Apache HTTPD 2.3.11 and later

If authentication succeeds but authorization fails, Apache HTTPD will respond with an HTTP response code of '401 UNAUTHORIZED' by default. This usually causes browsers to display the password dialogue to the user again, which is not wanted in all situations. AuthzSendForbiddenOnFailure allows to change the response code to '403 FORBIDDEN'.

Security Warning

Modifying the response in case of missing authorization weakens the security of the password, because it reveals to a possible attacker, that his guessed password was right.

Require Directive

Description: | Tests whether an authenticated user is authorized by an authorization provider.
Syntax: | Require [not] entity-name [entity-name] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_core

This directive tests whether an authenticated user is authorized according to a particular authorization provider and the specified restrictions. mod_authz_core provides the following generic authorization providers:

Require all granted
Access is allowed unconditionally.
Require all denied
Access is denied unconditionally.
Require env env-var [env-var] ...
Access is allowed only if one of the given environment variables is set.
Require method http-method [http-method] ...
Access is allowed only for the given HTTP methods.
Require expr expression
Access is allowed if expression evaluates to true.

Some of the allowed syntaxes provided by mod_authz_user, mod_authz_host, and mod_authz_groupfile are:

Require user userid [userid] ...
Only the named users can access the resource.
Require group group-name [group-name] ...
Only users in the named groups can access the resource.
Require valid-user
All valid users can access the resource.
Require ip 10 172.20 192.168.2
Clients in the specified IP address ranges can access the resource.

Other authorization modules that implement require options include mod_authnz_ldap, mod_authz_dbm, mod_authz_dbd, mod_authz_owner and mod_ssl.

In most cases, for a complete authentication and authorization configuration, Require must be accompanied by AuthName, AuthType and AuthBasicProvider or AuthDigestProvider directives, and directives such as AuthUserFile and AuthGroupFile (to define users and groups) in order to work correctly. Example:

AuthType Basic
AuthName "Restricted Resource"
AuthBasicProvider file
AuthUserFile "/web/users"
AuthGroupFile "/web/groups"
Require group admin

Access controls which are applied in this way are effective for all methods. This is what is normally desired. If you wish to apply access controls only to specific methods, while leaving other methods unprotected, then place the Require statement into a <Limit> section.

The result of the Require directive may be negated through the use of the not option. As with the other negated authorization directive <RequireNone>, when the Require directive is negated it can only fail or return a neutral result, and therefore may never independently authorize a request.

In the following example, all users in the alpha and beta groups are authorized, except for those who are also in the reject group.

<Directory "/www/docs">
    <RequireAll>
        Require group alpha beta
        Require not group reject
    </RequireAll>
</Directory>

When multiple Require directives are used in a single configuration section and are not contained in another authorization directive like <RequireAll>, they are implicitly contained within a <RequireAny> directive. Thus the first one to authorize a user authorizes the entire request, and subsequent Require directives are ignored.

Security Warning

Exercise caution when setting authorization directives in Location sections that overlap with content served out of the filesystem. By default, these configuration sections overwrite authorization configuration in Directory, and Files sections.

The AuthMerging directive can be used to control how authorization configuration sections are merged.

See also

  • Access control howto
  • Authorization Containers
  • mod_authn_core
  • mod_authz_host

<RequireAll> Directive

Description: | Enclose a group of authorization directives of which none must fail and at least one must succeed for the enclosing directive to succeed.
Syntax: | <RequireAll> ... </RequireAll>
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_core

<RequireAll> and </RequireAll> are used to enclose a group of authorization directives of which none must fail and at least one must succeed in order for the <RequireAll> directive to succeed.

If none of the directives contained within the <RequireAll> directive fails, and at least one succeeds, then the <RequireAll> directive succeeds. If none succeed and none fail, then it returns a neutral result. In all other cases, it fails.

See also

  • Authorization Containers
  • Authentication, Authorization, and Access Control

<RequireAny> Directive

Description: | Enclose a group of authorization directives of which one must succeed for the enclosing directive to succeed.
Syntax: | <RequireAny> ... </RequireAny>
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_core

<RequireAny> and </RequireAny> are used to enclose a group of authorization directives of which one must succeed in order for the <RequireAny> directive to succeed.

If one or more of the directives contained within the <RequireAny> directive succeed, then the <RequireAny> directive succeeds. If none succeed and none fail, then it returns a neutral result. In all other cases, it fails.

Because negated authorization directives are unable to return a successful result, they can not significantly influence the result of a <RequireAny> directive. (At most they could cause the directive to fail in the case where they failed and all other directives returned a neutral value.) Therefore negated authorization directives are not permitted within a <RequireAny> directive.

See also

  • Authorization Containers
  • Authentication, Authorization, and Access Control

<RequireNone> Directive

Description: | Enclose a group of authorization directives of which none must succeed for the enclosing directive to not fail.
Syntax: | <RequireNone> ... </RequireNone>
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_core

<RequireNone> and </RequireNone> are used to enclose a group of authorization directives of which none must succeed in order for the <RequireNone> directive to not fail.

If one or more of the directives contained within the <RequireNone> directive succeed, then the <RequireNone> directive fails. In all other cases, it returns a neutral result. Thus as with the other negated authorization directive Require not, it can never independently authorize a request because it can never return a successful result. It can be used, however, to restrict the set of users who are authorized to access a resource.

Because negated authorization directives are unable to return a successful result, they can not significantly influence the result of a <RequireNone> directive. Therefore negated authorization directives are not permitted within a <RequireNone> directive.

See also

  • Authorization Containers
  • Authentication, Authorization, and Access Control


mod_authz_dbd - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_dbd

Description: | Group Authorization and Login using SQL
Status: | Extension
Module Identifier: | authz_dbd_module
Source File: | mod_authz_dbd.c
Compatibility: | Available in Apache 2.4 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site by group membership. Similar functionality is provided by mod_authz_groupfile and mod_authz_dbm, with the exception that this module queries a SQL database to determine whether a user is a member of a group.

This module can also provide database-backed user login/logout capabilities. These are likely to be of most value when used in conjunction with mod_authn_dbd.

This module relies on mod_dbd to specify the backend database driver and connection parameters, and manage the database connections.

See also

  • Require
  • AuthDBDUserPWQuery
  • DBDriver
  • DBDParams

The Require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authz_dbd extends the authorization types with dbd-group, dbd-login and dbd-logout.

Since v2.4.8, expressions are supported within the DBD require directives.

Require dbd-group

This directive specifies group membership that is required for the user to gain access.

      Require dbd-group team
      AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

Require dbd-login

This directive specifies a query to be run indicating the user has logged in.

      Require dbd-login
      AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

Require dbd-logout

This directive specifies a query to be run indicating the user has logged out.

      Require dbd-logout
      AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"

Database Login

In addition to the standard authorization function of checking group membership, this module can also provide server-side user session management via database-backed login/logout capabilities. Specifically, it can update a user's session status in the database whenever the user visits designated URLs (subject of course to users supplying the necessary credentials).

This works by defining two special Require types: Require dbd-login and Require dbd-logout. For usage details, see the configuration example below.

Client Login integration

Some administrators may wish to implement client-side session management that works in concert with the server-side login/logout capabilities offered by this module, for example, by setting or unsetting an HTTP cookie or other such token when a user logs in or out.

To support such integration, mod_authz_dbd exports an optional hook that will be run whenever a user's status is updated in the database. Other session management modules can then use the hook to implement functions that start and end client-side sessions.

Configuration example

# mod_dbd configuration
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache pass=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory "/usr/www/my.site/team-private/">
  # mod_authn_core and mod_auth_basic configuration
  # for mod_authn_dbd
  AuthType Basic
  AuthName Team
  AuthBasicProvider dbd

  # mod_authn_dbd SQL query to authenticate a logged-in user
  AuthDBDUserPWQuery \
    "SELECT password FROM authn WHERE user = %s AND login = 'true'"

  # mod_authz_core configuration for mod_authz_dbd
  Require dbd-group team

  # mod_authz_dbd configuration
  AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

  # when a user fails to be authenticated or authorized,
  # invite them to login; this page should provide a link
  # to /team-private/login.html
  ErrorDocument 401 "/login-info.html"

  <Files "login.html">
    # don't require user to already be logged in!
    AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

    # dbd-login action executes a statement to log user in
    Require dbd-login
    AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

    # return user to referring page (if any) after
    # successful login
    AuthzDBDLoginToReferer On
  </Files>

  <Files "logout.html">
    # dbd-logout action executes a statement to log user out
    Require dbd-logout
    AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
  </Files>
</Directory>

AuthzDBDLoginToReferer Directive

Description: | Determines whether to redirect the Client to the Referring page on successful login or logout if a Referer request header is present
Syntax: | AuthzDBDLoginToReferer On|Off
Default: | AuthzDBDLoginToReferer Off
Context: | directory
Status: | Extension
Module: | mod_authz_dbd

In conjunction with Require dbd-login or Require dbd-logout, this provides the option to redirect the client back to the Referring page (the URL in the Referer HTTP request header, if present). When there is no Referer header, AuthzDBDLoginToReferer On will be ignored.

AuthzDBDQuery Directive

Description: | Specify the SQL Query for the required operation
Syntax: | AuthzDBDQuery query
Context: | directory
Status: | Extension
Module: | mod_authz_dbd

The AuthzDBDQuery specifies an SQL query to run. The purpose of the query depends on the Require directive in effect.

  • When used with a Require dbd-group directive, it specifies a query to look up groups for the current user. This is the standard functionality of other authorization modules such as mod_authz_groupfile and mod_authz_dbm. The first column value of each row returned by the query statement should be a string containing a group name. Zero, one, or more rows may be returned.
    Require dbd-group
AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"
  • When used with a Require dbd-login or Require dbd-logout directive, it will never deny access, but will instead execute a SQL statement designed to log the user in or out. The user must already be authenticated with mod_authn_dbd.
    Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

In all cases, the user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a %s format specifier.

AuthzDBDRedirectQuery Directive

Description: | Specify a query to look up a login page for the user
Syntax: | AuthzDBDRedirectQuery query
Context: | directory
Status: | Extension
Module: | mod_authz_dbd

Specifies an optional SQL query to use after successful login (or logout) to redirect the user to a URL, which may be specific to the user. The user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a %s format specifier.

AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"

The first column value of the first row returned by the query statement should be a string containing a URL to which to redirect the client. Subsequent rows will be ignored. If no rows are returned, the client will not be redirected.

Note that AuthzDBDLoginToReferer takes precedence if both are set.


mod_authz_dbm - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_dbm

Description: | Group authorization using DBM files
Status: | Extension
Module Identifier: | authz_dbm_module
Source File: | mod_authz_dbm.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site by group membership. Similar functionality is provided by mod_authz_groupfile.

See also

  • Require

The Require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authz_dbm extends the authorization types with dbm-group.

Since v2.4.8, expressions are supported within the DBM require directives.

Require dbm-group

This directive specifies group membership that is required for the user to gain access.

Require dbm-group admin

Require dbm-file-group

When this directive is specified, the user must be a member of the group assigned to the file being accessed.

Require dbm-file-group

Example usage

Note that using mod_authz_dbm requires you to require dbm-group instead of group:

<Directory "/foo/bar">
  AuthType Basic
  AuthName "Secure Area"
  AuthBasicProvider dbm
  AuthDBMUserFile "site/data/users"
  AuthDBMGroupFile "site/data/users"
  Require dbm-group admin
</Directory>

AuthDBMGroupFile Directive

Description: | Sets the name of the database file containing the list of user groups for authorization
Syntax: | AuthDBMGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authz_dbm

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user authorization. File-path is the absolute path to the group file.

The group file is keyed on the username. The value for a user is a comma-separated list of the groups to which the users belongs. There must be no whitespace within the value, and it must never contain any colons.

Security

Make sure that the AuthDBMGroupFile is stored outside the document tree of the web-server. Do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMGroupFile unless otherwise protected.

Combining Group and Password DBM files: In some cases it is easier to manage a single database which contains both the password and group details for each user. This simplifies any support programs that need to be written: they now only have to deal with writing to and locking a single DBM file. This can be accomplished by first setting the group and password files to point to the same DBM:

AuthDBMGroupFile "/www/userbase"
AuthDBMUserFile "/www/userbase"

The key for the single DBM is the username. The value consists of

Encrypted Password : List of Groups [ : (ignored) ]

The password section contains the encrypted password as before. This is followed by a colon and the comma separated list of groups. Other data may optionally be left in the DBM file after another colon; it is ignored by the authorization module. This is what www.telescope.org uses for its combined password and group database.

AuthzDBMType Directive

Description: | Sets the type of database file that is used to store list of user groups
Syntax: | AuthzDBMType default|SDBM|GDBM|NDBM|DB
Default: | AuthzDBMType default
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authz_dbm

Sets the type of database file that is used to store the list of user groups. The default database type is determined at compile time. The availability of other types of database files also depends on compile-time settings.

It is crucial that whatever program you use to create your group files is configured to use the same type of database.


mod_authz_groupfile - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_groupfile

Description: | Group authorization using plaintext files
Status: | Base
Module Identifier: | authz_groupfile_module
Source File: | mod_authz_groupfile.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site by group membership. Similar functionality is provided by mod_authz_dbm.

See also

  • Require

The Require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authz_groupfile extends the authorization types with group and group-file.

Since v2.4.8, expressions are supported within the groupfile require directives.

Require group

This directive specifies group membership that is required for the user to gain access.

Require group admin

Require file-group

When this directive is specified, the user must be a member of the group assigned to the file being accessed.

Require file-group

AuthGroupFile Directive

Description: | Sets the name of a text file containing the list of user groups for authorization
Syntax: | AuthGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_authz_groupfile

The AuthGroupFile directive sets the name of a textual file containing the list of user groups for user authorization. File-path is the path to the group file. If it is not absolute, it is treated as relative to the ServerRoot.

Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces.

Example:

mygroup: bob joe anne

Note that searching large text files is very inefficient; AuthDBMGroupFile provides a much better performance.

Security

Make sure that the AuthGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthGroupFile.


mod_authz_host - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_host

Description: | Group authorizations based on host (name or IP address)
Status: | Base
Module Identifier: | authz_host_module
Source File: | mod_authz_host.c
Compatibility: | The forward-dns provider was addded in 2.4.19

Summary

The authorization providers implemented by mod_authz_host are registered using the Require directive. The directive can be referenced within a <Directory>, <Files>, or <Location> section as well as .htaccess files to control access to particular parts of the server. Access can be controlled based on the client hostname or IP address.

In general, access restriction directives apply to all access methods (GET, PUT, POST, etc). This is the desired behavior in most cases. However, it is possible to restrict some methods, while leaving other methods unrestricted, by enclosing the directives in a <Limit> section.

See also

  • Authentication, Authorization, and Access Control
  • Require

The Require Directives

Apache's Require directive is used during the authorization phase to ensure that a user is allowed or denied access to a resource. mod_authz_host extends the authorization types with ip, host, forward-dns and local. Other authorization types may also be used but may require that additional authorization modules be loaded.

These authorization providers affect which hosts can access an area of the server. Access can be controlled by hostname, IP Address, or IP Address range.

Since v2.4.8, expressions are supported within the host require directives.

Require ip

The ip provider allows access to the server to be controlled based on the IP address of the remote client. When Require ip ip-address is specified, then the request is allowed access if the IP address matches.

A full IP address:

Require ip 10.1.2.3
Require ip 192.168.1.104 192.168.1.205

An IP address of a host allowed access

A partial IP address:

Require ip 10.1
Require ip 10 172.20 192.168.2

The first 1 to 3 bytes of an IP address, for subnet restriction.

A network/netmask pair:

Require ip 10.1.0.0/255.255.0.0

A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction.

A network/nnn CIDR specification:

Require ip 10.1.0.0/16

Similar to the previous case, except the netmask consists of nnn high-order 1 bits.

Note that the last three examples above match exactly the same set of hosts.

IPv6 addresses and IPv6 subnets can be specified as shown below:

Require ip 2001:db8::a00:20ff:fea7:ccea
Require ip 2001:db8:1:1::a
Require ip 2001:db8:2:1::/64
Require ip 2001:db8:3::/48

Note: As the IP addresses are parsed on startup, expressions are not evaluated at request time.

Require host

The host provider allows access to the server to be controlled based on the host name of the remote client. When Require host host-name is specified, then the request is allowed access if the host name matches.

A (partial) domain-name

Require host example.org
Require host .net example.edu

Hosts whose names match, or end in, this string are allowed access. Only complete components are matched, so the above example will match foo.example.org but it will not match fooexample.org. This configuration will cause Apache to perform a double reverse DNS lookup on the client IP address, regardless of the setting of the HostnameLookups directive. It will do a reverse DNS lookup on the IP address to find the associated hostname, and then do a forward lookup on the hostname to assure that it matches the original IP address. Only if the forward and reverse DNS are consistent and the hostname matches will access be allowed.

Require forward-dns

The forward-dns provider allows access to the server to be controlled based on simple host names. When Require forward-dns host-name is specified, all IP addresses corresponding to host-name are allowed access.

In contrast to the host provider, this provider does not rely on reverse DNS lookups: it simply queries the DNS for the host name and allows a client if its IP matches. As a consequence, it will only work with host names, not domain names. However, as the reverse DNS is not used, it will work with clients which use a dynamic DNS service.

Require forward-dns bla.example.org

A client the IP of which is resolved from the name bla.example.org will be granted access.

The forward-dns provider was added in 2.4.19.

Require local

The local provider allows access to the server if any of the following conditions is true:

  • the client address matches 127.0.0.0/8
  • the client address is ::1
  • both the client and the server address of the connection are the same

This allows a convenient way to match connections that originate from the local host:

Require local

Security Note

If you are proxying content to your server, you need to be aware that the client address will be the address of your proxy server, not the address of the client, and so using the Require directive in this context may not do what you mean. See mod_remoteip for one possible solution to this problem.


mod_authz_owner - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_owner

Description: | Authorization based on file ownership
Status: | Extension
Module Identifier: | authz_owner_module
Source File: | mod_authz_owner.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module authorizes access to files by comparing the userid used for HTTP authentication (the web userid) with the file-system owner or group of the requested file. The supplied username and password must be already properly verified by an authentication module, such as mod_auth_basic or mod_auth_digest. mod_authz_owner recognizes two arguments for the Require directive, file-owner and file-group, as follows:

file-owner
The supplied web-username must match the system's name for the owner of the file being requested. That is, if the operating system says the requested file is owned by jones, then the username used to access it through the web must be jones as well.
file-group
The name of the system group that owns the file must be present in a group database, which is provided, for example, by mod_authz_groupfile or mod_authz_dbm, and the web-username must be a member of that group. For example, if the operating system says the requested file is owned by (system) group accounts, the group accounts must appear in the group database and the web-username used in the request must be a member of that group.

Note

If mod_authz_owner is used in order to authorize a resource that is not actually present in the filesystem (i.e. a virtual resource), it will deny the access.

Particularly it will never authorize content negotiated "MultiViews" resources.

See also

  • Require

Configuration Examples

Require file-owner

Consider a multi-user system running the Apache Web server, with each user having his or her own files in ~/public_html/private. Assuming that there is a single AuthDBMUserFile database that lists all of their web-usernames, and that these usernames match the system's usernames that actually own the files on the server, then the following stanza would allow only the user himself access to his own files. User jones would not be allowed to access files in /home/smith/public_html/private unless they were owned by jones instead of smith.

<Directory "/home/*/public_html/private">
    AuthType Basic
    AuthName MyPrivateFiles
    AuthBasicProvider dbm
    AuthDBMUserFile "/usr/local/apache2/etc/.htdbm-all"
    Require file-owner
</Directory>

Require file-group

Consider a system similar to the one described above, but with some users that share their project files in ~/public_html/project-foo. The files are owned by the system group foo and there is a single AuthDBMGroupFile database that contains all of the web-usernames and their group membership, i.e. they must be at least member of a group named foo. So if jones and smith are both member of the group foo, then both will be authorized to access the project-foo directories of each other.

<Directory "/home/*/public_html/project-foo">
    AuthType Basic
    AuthName "Project Foo Files"
    AuthBasicProvider dbm

    # combined user/group database
    AuthDBMUserFile  "/usr/local/apache2/etc/.htdbm-all"
    AuthDBMGroupFile "/usr/local/apache2/etc/.htdbm-all"

    Satisfy All
    Require file-group
</Directory>

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authz_user - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authz_user

Description: | User Authorization
Status: | Base
Module Identifier: | authz_user_module
Source File: | mod_authz_user.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site. mod_authz_user grants access if the authenticated user is listed in a Require user directive. Alternatively Require valid-user can be used to grant access to all successfully authenticated users.

See also

  • Require

The Require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authz_user extends the authorization types with user and valid-user.

Since v2.4.8, expressions are supported within the user require directives.

Require user

This directive specifies a list of users that are allowed to gain access.

Require user john paul george ringo

Require valid-user

When this directive is specified, any successfully authenticated user will be allowed to gain access.

Require valid-user

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_autoindex - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_autoindex

Açıklama: | Unix ls veya Win32 dir kabuk komutunun yaptığı gibi dizin içeriğini listeler.
Durum: | Temel
Modül Betimleyici: | autoindex_module
Kaynak Dosyası: | mod_autoindex.c

Özet

Bir dizin içerik dosyası iki kaynaktan gelebilir:

  • Bu dizinde bulunan ve genellikle index.html adında bir dosya olarak. Kullanılan dosyanın veya dosyaların ismi DirectoryIndex yönergesi ile belirlenir ve mod_dir tarafından denetlenir.
  • Kullanıcı tarafından böyle bir dosya sağlanmadığı takdirde dizin içerik listesini sunucu üretir. Diğer yönergeler bu listenin biçemini belirler. Listede gösterilen dosya türü simgeleri AddIcon, AddIconByEncoding ve AddIconByType yönergeleri ile belirlenir. Bunlar mod_autoindex tarafından denetlenir.

İki işlev birbirinden ayrı tutulmuştur, böylece kendiliğinden içerik listesi üretimi tamamen iptal edilebilir (veya değiştirilebilir).

Kendiliğinden içerik listesi üretimi Options +Indexes ile etkin kılınabilir. Daha fazla bilgi için Options yönergesinin açıklamasına bakınız.

IndexOptions yönergesi FancyIndexing seçeneği ile kullanılmışsa sütun başlıkları listenin sıralamasını sütundaki sıralamaya göre değiştirecek hiper bağlar haline getirilir (süslü liste). Aynı başlığa peşpeşe tıklamak suretiyle sıralamayı büyükten küçüğe veya tersine değiştirebilirsiniz. Bu sütun başlığı bağlarının oluşturulması IndexOptions yönergesi SuppressColumnSorting seçeneği ile kullanılarak engellenebilir.

Boyuta göre sıralamada daima dosyanın asıl boyutuna bakılır. Dolayısıyla ikisi de "1K" olarak gösterilen iki dosyadan 1010 baytlık olanı küçükten büyüğe sıralamada 1011 baytlıktan önce gösterilecektir.

Sütun Sıralamada Sorgu Seçenekleri

İstemciye, dizin içeriğini listelerken neleri hangi sırada listeleyeceğini belirleyebilmesi için içerik üzerinde biraz denetim sağlayabileceği çeşitli sorgu dizgesi bileşenleri sağlanmıştır. Çıktı üzerinde kullanıcı denetimini tamamen ortadan kaldırmak için IndexOptions yönergesinin IgnoreClient seçeneği kullanılabilir.

Sütun sıralama başlıklarının her biri hedefi kendisi olan birer hiper bağ olup aşağıda sıralanan sorgu seçeneklerini kullanırlar. Bu seçeneklerin her biri her dizin içerik listesi isteğine eklenebilir.

  • C=N dizini dosya adına göre sıralar
  • C=M dizini son değişiklik zamanına ve ardından dosya ismine göre sıralar.
  • C=S dizini boyuta ve ardından dosya adına göre sıralar
  • C=D dizini açıklamaya ve ardından dosya adına göre sıralar.
  • O=A artan sıralama uygulanır.
  • O=D azalan sıralama uygulanır.
  • F=0 listeleme basit listeleme biçiminde yapılır (FancyIndexing seçeneği ile etkinleştirilen biçimde değil)
  • F=1 listeleme FancyIndexing seçeneği ile etkinleştirilen biçimde yapılır
  • F=2 listeleme FancyIndexing ve HTMLTable seçeneği ile etkinleştirilen biçimde yapılır.
  • V=0 sürüme göre sıralama iptal edilir.
  • V=1 sürüme göre sıralama etkin kılınır.
  • P=kalıp sadece belirtilen kalıp ile eşleşen dosyalar istelenir.

P=kalıp sorgu seçeneğinin normalde IndexIgnore yönergesi işleme sokulduktan sonra değerlendirildiğine ve dosya isimlerinin diğer kendiliğinden içerik listeleme koşullarının konusu olmaya devam ettiğine dikkat ediniz. mod_autoindex modülündeki Sorgu Seçenekleri çözümleyicisi tanımadığı bir seçeneğe rastlar rastlamaz işlemi durdurur. Sorgu Seçenekleri yukarıda belirtilene uygun olarak iyi biçimli olmak zorundadır.

Aşağıdaki basit örnekte sorgu seçeneklerinin kullanımı gösterilmiştir. Son satırda bulunan "submit" düğmesindeki tanınmayan "X" girdisine dikkat ediniz. "X=Göster" girdisi tüm seçenekler işlendikten sonra mod_autoindex tarafından son argüman olarak ele alınacak ve çözümleme işlemi o noktada duracaktır.

<form action="" method="get">
  <input type="text" name="P" value="*" /> ile eşleşen
  <select name="C">
    <option value="N" selected="selected">isme</option>
    <option value="M"> değişiklik tarihine</option>
    <option value="S"> boyuta</option>
    <option value="D"> açıklamaya</option>
  </select> göre
  <select name="O">
    <option value="A" selected="selected"> artan</option>
    <option value="D"> azalan</option>
  </select>
  <select name="V">
    <option value="0" selected="selected">normal</option>
    <option value="1"> sürümlü</option>
  </select> sıralamayla bir
  <select name="F">
    <option value="0"> basit liste</option>
    <option value="1" selected="selected"> süslü liste</option>
    <option value="2"> tablolu liste</option>
  </select>
  <input type="submit" name="X" value="Göster" />
</form>

AddAlt Yönergesi

Açıklama: | Dosyaya göre seçilen simgenin yerinde gösterilecek metni belirler.
Sözdizimi: | AddAlt metin dosya [dosya] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

AddAlt yönergesi, FancyIndexing seçeneğiyle üretilen dizin listesinde bir dosya simgesinin yerinde gösterilecek metni belirler. dosya olarak dosya türünü betimleyecek bir dosya uzantısı, dosya isminin bir kısmı, bir dosya ismi kalıbı veya tam yoluyla bir dosya ismi belirtilebilir. Eğer metin boşluk karakterleri içeriyorsa tırnak içine (" veya ') alınmalıdır. Simge metni, simge bulunamadığı veya istemci resim gösteremediği takdirde ya da kullanıcı resim yüklememeyi tercih etmişse gösterilir.

AddAlt "PDF file" *.pdf
AddAlt Compressed *.gz *.zip *.Z

AddAltByEncoding Yönergesi

Açıklama: | Dosyanın MIME kodlamasına göre seçilen simgenin yerinde gösterilecek metni belirler.
Sözdizimi: | AddAltByEncoding metin MIME-kodlaması [MIME-kodlaması] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

AddAltByEncoding yönergesi, FancyIndexing seçeneğiyle üretilen dizin listesinde bir dosya simgesinin yerinde gösterilecek metni belirler. MIME-kodlaması olarak x-compress gibi geçerli bir içerik kodlaması belirtilmelidir. Eğer metin boşluk karakterleri içeriyorsa tırnak içine (" veya ') alınmalıdır. Simge metni simge bulunamadığı veya istemci resim gösteremediği takdirde ya da kullanıcı resim yüklememeyi tercih etmişse gösterilir.

AddAltByEncoding gzip x-gzip

AddAltByType Yönergesi

Açıklama: | Dosyanın MIME türüne göre seçilen simgenin yerinde gösterilecek metni belirler.
Sözdizimi: | AddAltByType metin MIME-türü [MIME-türü] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

AddAltByType yönergesi, FancyIndexing seçeneğiyle üretilen dizin listesinde bir dosya simgesinin yerinde gösterilecek metni belirler. MIME-türü olarak text/html gibi geçerli bir içerik türü belirtilmelidir. Eğer metin boşluk karakterleri içeriyorsa tırnak içine (" veya ') alınmalıdır. Simge metni simge bulunamadığı veya istemci resim gösteremediği takdirde ya da kullanıcı resim yüklememeyi tercih etmişse gösterilir.

AddAltByType 'salt metin' text/plain

AddDescription Yönergesi

Açıklama: | Bir dosya için gösterilecek açıklama belirtilir.
Sözdizimi: | AddDescription metin dosya [dosya] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

Yönerge, FancyIndexing seçeneğiyle üretilen dizin listesinde bir dosya için gösterilecek açıklamayı belirler. dosya olarak dosya türünü betimleyecek bir dosya uzantısı, dosya isminin bir kısmı, bir dosya ismi kalıbı veya tam yoluyla bir dosya ismi belirtilebilir. Eğer dosya açıklamasını içeren metin boşluk karakterleri içeriyorsa çift tırnak (") içine alınmalıdır.

AddDescription "Mars Gezegeni" mars.gif

AddDescription "Dostum Marshall" dostlar/mars.gif

Normalde öntanımlı açıklama alanının genişliği 23 bayttır. IndexOptions SuppressIcon seçeneği buna 6 bayt daha ekler; IndexOptions SuppressSize seçeneği 7 bayt, IndexOptions SuppressLastModified seçeneği ise 19 bayt ekler. Böylece en fazla 55 karakterlik öntanımlı sütun genişliğine ulaşılabilir.

dosya kısmî dosya ismi içerebileceğinden çok kısa dosya ismi belirtilmesi yüzünden istemeden de olsa başka dosyalarla eşleşebileceğini unutmayın. Örneğin, le.html doğrudan le.html ile eşleşebileceği gibi example.html ile de eşleşecektir. Şüpheli durumların ortaya çıkabileceği durumlarda mümkün olduğunca dosya isminin tamamını kullanın ve saptanan ilk eşleşmenin kullanılacağını aklınızdan çıkarmayın ayrıca, AddDescription listesini de uygun şekilde sıralayın.

Açıklama sütununun öntanımlı genişliği geçersiz kılınabilir hatta sınırsız açıklama uzunluğu atanabilir. Bu konu için IndexOptions yönergesinin DescriptionWidth seçeneğinin açıklamasına bakınız.

Önemli

AddDescription ile tanımlanan açıklama metni HTML etiketleri ve karakter öğeleri içerebilir. Eğer açıklama sütununun genişlik sınırlamasından dolayı bir HTML etiketinin içeriği kırpılırsa bu durum dizin listesinin kalanını etkileyebilir (örneğin, kalın gösterim listenin kalanına yayılabilir).

Yol bilgisi içeren değiştirgeler

Mutlak yollar henüz desteklenmemetedir ve çalışma anında hiçbir şeyle eşleşmeyeceklerdir. Normalde sadece htaccess bağlamında kullanılan, göreli yol bilgisi içeren değiştirgeler, kısmi dizin isimleriyle eşleşmemeleri için örtük olarak '*/' öneki alırlar.

AddIcon Yönergesi

Açıklama: | Bir dosya için gösterilecek simgeyi dosya adına göre belirler.
Sözdizimi: | AddIcon simge isim [isim] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

Yönerge, FancyIndexing seçeneğiyle üretilen dizin listesinde adı isim ile biten bir dosya için gösterilecek simgeyi belirler. simge ya simgenin göreli URL’si (% öncelemeli), tam nitelenmiş bir uzak URL ya da (alt-metin,url) biçeminde olmalıdır; buradaki alt-metin simge gösterilemediği durumda tarayıcı tarafından simgenin yerinde gösterilecek metindir.

isim olarak ya (listeyi düzgün biçemlemek amacıyla) dizinler için ^^DIRECTORY^^, boş satırlar için ^^BLANKICON^^ ya da dosya türünü betimleyecek bir dosya uzantısı, dosya isminin bir kısmı, bir dosya ismi kalıbı veya tam yoluyla bir dosya ismi belirtilebilir.

^^BLANKICON^^ sadece biçemleme için kullanılır, dolayısıyla IndexOptions HTMLTable kullanıyorsanız gereksizdir.

#Examples
AddIcon (IMG,/icons/image.png) .gif .jpg .png
AddIcon /icons/dir.png ^^DIRECTORY^^
AddIcon /icons/backup.png *~

Mümkünse AddIcon yerine AddIconByType yönergesi tercih edilmelidir.

AddIconByEncoding Yönergesi

Açıklama: | Bir dosya için gösterilecek simgeyi dosyanın MIME kodlamasına göre belirler.
Sözdizimi: | AddIconByEncoding simge MIME-kodlaması [MIME-kodlaması] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

Yönerge, FancyIndexing seçeneğiyle üretilen dizin listesinde bir dosya için gösterilecek simgeyi belirler. simge ya simgenin göreli URL’si (% öncelemeli), tam nitelenmiş uzak bir URL ya da (alt-metin,url) biçeminde olmalıdır; buradaki alt-metin simge gösterilemediği durumda tarayıcı tarafından simgenin yerinde gösterilecek metindir.

MIME-kodlaması olarak x-compress gibi geçerli bir içerik kodlaması belirtilmelidir.

AddIconByEncoding /icons/compress.png x-compress

AddIconByType Yönergesi

Açıklama: | Bir dosya için gösterilecek simgeyi dosyanın MIME türüne göre belirler.
Sözdizimi: | AddIconByType simge MIME-türü [MIME-türü] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

Yönerge, FancyIndexing seçeneğiyle üretilen dizin listesinde MIME türü MIME-türü olarak belirtilen bir dosya için gösterilecek simgeyi belirler. simge ya simgenin göreli URL’si (% öncelemeli), tam nitelenmiş uzak bir URL ya da (alt-metin,url) biçeminde olmalıdır; buradaki alt-metin simge gösterilemediği durumda tarayıcı tarafından simgenin yerinde gösterilecek metindir.

MIME-türü MIME türleri ile eşleşen bir dosya kalıbı ifadesi olabilir.

AddIconByType (IMG,/icons/image.png) image/*

DefaultIcon Yönergesi

Açıklama: | Özel bir simge atanmamış dosyalar için gösterilecek simgeyi belirler.
Sözdizimi: | DefaultIcon URL-yolu
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

The DefaultIcon yönergesi FancyIndexing seçeneğiyle üretilen dizin listesinde özel bir simge atanmamış dosyalar için gösterilecek simgeyi belirler. URL-yolu simgeye bir göreli URL (% öncelemeli) veya tam nitelenmiş uzak bir URL belirtir.

DefaultIcon /icon/unknown.png

HeaderName Yönergesi

Açıklama: | Dizin listesinin tepesine yerleştirilecek dosyanın ismini belirler.
Sözdizimi: | HeaderName dosya-ismi
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

HeaderName yönergesi, dizin listesinin tepesine yerleştirilecek dosyanın ismini belirler. Dosyanın ismi dosya-ismi ile belirtilir.

HeaderName HEADER.html

HeaderName and ReadmeName yönergelerinde dosya-ismi artık içeriği listelenecek dizine erişmek için kullanılan bir göreli URL yolu olarak ele alınmaktadır. Eğer dosya-ismi bir bölü çizgisi ("/") ile başlıyorsa DocumentRoot yönergesinde belirtilen dizine göre belirtildiği varsayılır.

HeaderName /include/HEADER.html

dosya-ismi, içerik türü text/* (text/html, text/plain gibi) olan bir belge olarak çözümlenmelidir. Yani, aşağıdaki örnekteki gibi betiğin asıl dosya türü text/html olarak imlenmişse dosya-ismi bir CGI betiğinin ismi bile olabilir:

AddType text/html .cgi

Options ile MultiViews etkin kılınmışsa dosyaya içerik dili uzlaşımı da uygulanabilir. dosya-ismi ile belirtilen dosya text/html türünde durağan bir belge (bir CGI betiği değil) ise ve options ile Includes ve IncludesNOEXEC seçeneklerinden biri belirtilmişse dosya bir SSI sayfası olarak ele alınır (mod_include belgesine bakınız).

Eğer yönergede belirtilen dosya bir HTML belge gibi başlıyorsa (<html>, <head>, vs.) ve bu etiketlerin yinelenmemesini istiyorsanız IndexOptions +SuppressHTMLPreamble ataması yapmanız gerekecektir.

Ayrıca bakınız:

  • ReadmeName

IndexHeadInsert Yönergesi

Açıklama: | Bir dizin sayfasının HEAD bölümüne metin yerleştirir.
Sözdizimi: | IndexHeadInsert "imlenim ..."
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

IndexHeadInsert yönergesi, dizin listesi için üretilen HTML’nin <head> bölümüne yerleştirilecek bir dizge tanımlar.

IndexHeadInsert "<link rel=\"sitemap\" href=\"/sitemap.html\">"

IndexIgnore Yönergesi

Açıklama: | Dizin içerik listesinden gizlenecek dosyaların listesi belirtilir.
Sözdizimi: | IndexIgnore dosya [dosya] ...
Öntanımlı: | IndexIgnore "."
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

IndexIgnore yönergesi, dizin içerik listesinden gizlenecek dosyaların listesini belirtmek için kullanılır. dosya olarak kabuk tarzı bir dosya ismi kalıbı veya tam yoluyla bir dosya ismi belirtilebilir. Evvelce yapılmış bir atamada değişiklik yapmak yerine birden fazla IndexIgnore ataması yapabilirsiniz. Liste öntanımlı olarak içinde bulunulan dizini (./) içerir.

IndexIgnore .??* *~ *# HEADER* README* RCS CVS *,v *,t

Düzenli İfadeler

Bu yönerge, <DirectoryMatch> gibidüzenli ifadeler içeren yapılandırma bölümlerinde henüz çalışmamaktadır.

IndexIgnoreReset Yönergesi

Açıklama: | Bir dizini listelerken gizlenecek dosyalar listesini boşaltır
Sözdizimi: | IndexIgnoreReset ON|OFF
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex
Uyumluluk: | Apache HTTP Sunucusunun 2.3.10 ve sonraki sürümlerinde kullanılabilmektedir.

Bu yönerge, diğer yapılandırma bölümlerince bir şekilde miras alınmayan ve IndexIgnore tarafından yoksayılan dosyaları kaldırır.

<Directory "/var/www">
    IndexIgnore *.bak .??* *~ *# HEADER* README* RCS CVS *,v *,t
</Directory>
<Directory "/var/www/backups">
    IndexIgnoreReset ON
    IndexIgnore .??* *# HEADER* README* RCS CVS *,v *,t
</Directory>

Bu yönergeyi kullandıktan sonra, açıkça yoksaymak istediğiniz kalıpların bir listesi için öntanımlı yapılandırmayı gözden geçirin.

IndexOptions Yönergesi

Açıklama: | Dizin içerik listesini yapılandıracak seçenekler belirtilir.
Sözdizimi: | IndexOptions [+|-]seçenek [[+|-]seçenek] ...
Öntanımlı: | Öntanımlı olarak hiçbir seçenek etkin değildir.
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

IndexOptions yönergesi dizin içerik listesinin davranışını belirler. seçenek olarak şunlar belirtilebilir:

AddAltClass
IndexOptions HTMLTable etkin ve bir IndexStyleSheet tanımlı olduğunda dizin listesi tablosunun her satırına fazladan bir CSS sınıfı bildirimi ekler. Tablonun her satırına uygulanmaması için standart even ve odd sınıfları yerine even-ALT ve odd-ALT bildirimleri kullanılabilir. Burada ALT ya bir dosya biçimiyle ilişkili standat bir alt dizgesidir ya da AddAlt* yönergeleriyle tanımlanan bir alt dizgesidir.
Charset=karakter-kümesi (Apache HTTP Sunucusunun 2.0.61 ve sonraki sürümleri)
Charset seçeneği üretilen sayfa için bir karakter kümesi belirtebilmenizi sağlar. Dizinin bulunduğu dosya sisteminin karakter kodlamasına bağlı olarak öntanımlı değeri Windows ve Mac OS X'te UTF-8, diğerlerinde ISO-8859-1’dir (İlgili dosya sisteminin Unicode dosya isimleri kullanıp kullanmamasına bağlıdır).
IndexOptions Charset=UTF-8
DescriptionWidth=[n | *]

DescriptionWidth seçeneği üretilen sayfada açıklama sütununun genişliğini sizin belirleyebilmenizi sağlar. Bu seçenek kullanılmadığında veya -DescriptionWidth olarak belirtildiğinde uygun genişliği mod_autoindex hesaplar.

DescriptionWidth=n ile açıklama sütununun genişliği n baytla sınırlanır.

DescriptionWidth=* ile açıklama sütununun genişliği en uzun açıklama metni sığacak şekilde arttırılır.

Sütun genişliğinin sabitliği nedeniyle metnin kırpılmasından kaynaklanan sorunlar için AddDescription yönergesinin açıklamasına bakınız.

FancyIndexing
Dizin içerik listesi süslü olur.
FoldersFirst
Bu seçenek etkin kılındığında dizin içerik listesinde alt dizinler dosyalardan önce listelenir. Listelemede genel olarak iki bileşen vardır: Alt dizinler ve dosyalar. Her biri kendi arasında sıraya dizilir ve alt dizinlerin tamamı dosyalardan önce gösterilir. Örneğin sıralama isme göre azalan sırada yapılıyorsa ve FoldersFirst etkinse Zed dizini listede Beta dizininden ve Gamma ve Alpha dosyalarından önce yer alacaktır. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
HTMLTable
FancyIndexing seçeneği ile birlikte süslü listeleme için basit bir tablo oluşturur. UTF-8'in etkin olduğu platformlarda gereklidir. Bununla birlikte, Linux, WinNT gibi sağdan sola veya soldan sağa yazım yönünün değiştiği platformlarda dosya isimleri ve açıklamalar için bu özellikle gerekli olabilir.
IconsAreLinks
Bu seçenek FancyIndexing seçeneği ile birlikte süslü listelemede dosya simgesini dosyaya bir hiper bağ haline getirir.
IconHeight[=benek-sayısı]
Bu seçeneğin varlığı IconWidth seçeneği ile kullanıldığında dosya simgesinin img etiketinin height ve width özniteliklerini içermesine sebep olur. Böylece tarayıcının tüm simgelerin yüklenmesini beklemeden sayfa yerleşimi için bir ön hesaplama yapabilmesi mümkün olur. Seçenek bir değer belirtilmeksizin kullanıldığında Apache http tarafından atanmış standart simge yüksekliği öntanımlıdır. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
IconWidth[=benek-sayısı]
Bu seçeneğin varlığı IconHeight seçeneği ile kullanıldığında dosya simgesinin img etiketinin height ve width özniteliklerini içermesine sebep olur. Böylece tarayıcının tüm simgelerin yüklenmesini beklemeden sayfa yerleşimi için bir ön hesaplama yapabilmesi mümkün olur. Seçenek bir değer belirtilmeksizin kullanıldığında Apache httpd tarafından atanmış standart simge genişliği öntanımlıdır.
IgnoreCase
Bu seçenek etkin kılındığında isimler harf büyüklüğüne duyarsız sıralanır. Örneğin, isme göre artan sıralamada IgnoreCase etkinse Zeta dosyası alfa dosyasından sonra listelenir (Dikkat: GAMMA daima gamma’dan önce listelenir.)
IgnoreClient
Bu seçenek mod_autoindex’in listenin sıralanmasına etki edenler dahil tüm sorgu değişkenlerini yoksaymasına sebep olur (örtük olarak SuppressColumnSorting uygulanır).
NameWidth=[n | *]

NameWidth seçeneği dosya ismi sütunu için bir genişlik belirtebilmenizi mümkün kılar.

Hiç belirtilmediğinde veya -NameWidth biçeminde belirtildiğinde mod_autoindex uygun genişliği kendisi hesaplayacaktır, fakat en fazla 20 karakter olabilir.

NameWidth=n ile sütun genişliği n bayt genişlikte sabitlenir.

NameWidth=* olduğunda ise sütun genişliği en geniş satırın sığacağı kadar arttırılır.

ScanHTMLTitles
Bu seçenek süslü listeleme için HTML belgelerden sayfa başlığının okunmasını sağlar. Dosya için AddDescription ile bir açıklama tanımlanmımışsa Apache httpd belgenin title etiketinin içeriğini okuyacaktır. Bu seçenek işlemciyi ve diski fazla meşgul eder.
ShowForbidden
Alt istek HTTP_UNAUTHORIZED veya HTTP_FORBIDDEN döndürdüğünden dolayı normalde gizli olan dosyalar bu seçenek belirtilmişse listede gösterilir.
SuppressColumnSorting
Bu seçenek belirtilmişse Apache, süslü dizin listesinde sütun başlıklarını sıralama için hiper bağ haline getirmeyecektir. Sütun başlıkları için öntanımlı davranış hiper bağ olmak olup bunlar seçilerek dizin listesinin o sütundaki değerlere göre sıralanması sağlanır. Bu davranış IndexOptions IgnoreClient ile sağlanmaktadır.
SuppressDescription
Süslü listelemede dosya açıklamalarının gösterilmesini engeller. Öntanımlı olarak hiçbir dosya açıklaması tanımlı değildir, dolayısıyla bu seçenek kullanılarak ekran genişliğinden 23 karakterlik yer kazanılabilir. Dosya açıklamalarının nasıl belirlendiğini öğrenmek için AddDescription yönergesinin açıklamasına bakınız. Ayrıca, açıklama sütununun genişliğini ayarlayan DescriptionWidth dizin listeleme seçeneğine de bakınız. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
SuppressHTMLPreamble
Eğer dizin aslında HeaderName yönergesi ile belirtilmiş bir dosya içeriyorsa modül normal olarak bu dosyanın içeriğinin öncesine HTML başlangıç etiketlerini (<html>, <head>, vs.) yerleştirir. Bu seçenek bu davranışı iptal ederek modülün dosya içeriğinin başlangıcına bir şey eklememesini sağlar. Bu durumda başlık dosyasının uygun HTML etiketlerini içermesi gerekir. Böyle bir başlık dosyası yoksa normal olarak HTML başlangıç etiketleri üretilir. Eğer bir ReadmeName yönergesi de belirtilirse ve bu dosya mevcutsa, kapayan </body></html> etiketleri de çıktı bulunmaz. Buna dayanarak bu etiketleri de sizin koymanız gerekebilir.
SuppressIcon
Süslü dizin listesinde dosya simgelerinin gösterilmesini engeller. Son belirtim, süslü dizin listelemede kullanılan pre etiketinin içeriğinde img ve hr etiketlerinin bulunmasına izin vermediğinden SuppressIcon ve SuppressRules seçenekleri birlikte kullanılarak HTML 3.2 belirtimine uyum sağlanır.
SuppressLastModified
Süslü dizin listelemede son değişiklik tarihinin gösterilmesi engellenir. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
SuppressRules
Dizin listelemede hr etiketinin kullanımını engeller. Son belirtim, süslü dizin listelemede kullanılan pre etiketinin içeriğinde img ve hr etiketlerinin bulunmasına izin vermediğinden SuppressIcon ve SuppressRules seçenekleri birlikte kullanılarak HTML 3.2 belirtimine uyum sağlanır. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
SuppressSize
Süslü dizin listelemede dosya boyutunun gösterilmesi engellenir. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
TrackModified
Bu seçenek listelenen dizin için HTTP başlığında Last-Modified ve ETag alanlarının dönmesini sağlar. Sadece işletim sistemi veya dosya sistemi uygun stat() sonuçlarını döndürüyorsa bu geçerlidir. Bazı Unix sistemleri ve OS/2'nin JFS'si ile Win32’nin NTFS’i böyledir. Ancak OS/2 ve Win32 FAT dosya sistemleri böyle değildir. Bu özellik etkin kılındığında istemci veya vekil HEAD istekleriyle dosya listesindeki değişiklikleri izleyebilirler. Yalnız, bazı işletim sistemlerinin yeni ve silinmiş dosyaların izini iyi sürdüğü halde dizin içindeki dosyaların boyut ve tarih değişikliklerini izlemediklerine dikkat ediniz. Mevcut bir dosyanın boyut ve zaman damgasındaki değişiklikler Last-Modified başlığının güncellenmesini tüm Unix sistemlerinde sağlamaz. Bu gibi durumlarda bu seçeneğin kapalı kalması daha iyidir.
Type=MIME-türü
Type anahtar sözcüğü üretilen sayfanın MIME içerik türünün belirtilebilmesini sağlar. text/html öntanımlıdır.
IndexOptions Type=text/plain
VersionSort
VersionSort seçeneği isimlerinde sürüm numarası bulunan dosyaların sayısal sıralamaya uygun olarak sıralanmalarını sağlar. Normalde sıralama karakter sıralamasına göre yapılır, ardından sürüm numaralı dosyalar veya açıklamalar kendi aralarında sayısal sıralamaya tabi tutulur.

Örnek:

foo-1.7
foo-1.7.2
foo-1.7.12
foo-1.8.2
foo-1.8.2a
foo-1.12

Sıfır ile başlalan numaralara ondalık sayı muamelesi yapılır:

foo-1.001
foo-1.002
foo-1.030
foo-1.04

XHTML
XHTML seçeneği mod_autoindex’in kodu HTML 3.2’ye değil XHTML 1.0’a uygun üretmesini sağlar. Bu seçenek sadece FancyIndexing seçeneği etkinse etkili olacaktır.
+ veya - Önekli Seçenekler

Çok sayıda IndexOptions yönergesinin işlenebileceğine dikkat edin.

  • Tek bir dizin için çok sayıda IndexOptions yönergesi belirtilmişse bunlar ayrı ayrı değil birlikte ele alınır. Yani,
    <Directory "/foo">
    IndexOptions HTMLTable
    IndexOptions SuppressColumnsorting
</Directory>

    yapılandırmasındaki IndexOptions yönergeleri

    IndexOptions HTMLTable SuppressColumnsorting

    yönergesine eşdeğerdir.

  • Seçeneklerde + veya - önekleri kullanılabilmektedir.

+ veya - önekli seçeneklere rastlandığında bunlar mevcut (üst dizinden miras alınanlar ve/veya önceki atamalar) IndexOptions yönergelerine uygulanır. Ancak, önek kullanılmamış bir seçeneğe raslandığında, o noktada önceki ve miras alınmış bu tür seçenekler iptal edilir. Şu örneği ele alalım:

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize

Bunun net etkisi IndexOptions FancyIndexing +SuppressSize atamasına eşdeğerdir, çünkü öneksiz FancyIndexing seçeneği kendinden önceki önekli seçenekleri iptal etmiş fakat hemen ardından eklenmelerine izin vermiştir.

Belli bir dizine önceki seçenekleri temizleyerek koşulsuz olarak tamamen yeni seçenekler atamak istiyorsanız IndexOptions yönergesinde seçenekleri + veya - öneklerini kullanmadan belirtiniz.

IndexOrderDefault Yönergesi

Açıklama: | Dizin içerik listesinin öntanımlı sıralamasını belirler.
Sözdizimi: | IndexOrderDefault Ascending|Descending Name|Date|Size|Description
Öntanımlı: | IndexOrderDefault Ascending Name
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

IndexOrderDefault yönergesi FancyIndexing seçeneğinin etkin olduğu durumda işe yarar. Öntanımlı olarak süslü listelemede dizin içeriği dosya ismine göre artan sıralamayla listelenir. IndexOrderDefault yönergesi bu öntanımlı sıralamanın değiştirilmesini mümkün kılar.

IndexOrderDefault yönergesi iki değer alır. İlki sıralama yönünü belirtmek üzere Ascending (küçükten büyüğe) veya Descending (büyükten küçüğe) olmak zorundadır. İkinci değer ise birincil sıralama anahtarını belirtmek üzere Name, Date, Size ve Description sözcüklerinden biri olmalıdır (anlamları sırayla: İsim, Tarih, Boyut, Açıklama). İkincil sıralama anahtarı daima artan sıralamayla dosya ismidir.

Sütunun tepesindeki sıralama bağını kaldırmak için SuppressColumnSorting seçeneğinin yanında, sıralama tercihlerinizi geçersiz kılmak için sorgu dizgesine elle sıralama seçenekleri eklenmesini engellemek için IgnoreClient seçeneğini de kullanarak istemcinin listeyi yeniden sıralamasını engelleyebilirsiniz.

IndexStyleSheet Yönergesi

Açıklama: | Dizin listesine bir biçembent ekler.
Sözdizimi: | IndexStyleSheet url-yolu
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

IndexStyleSheet yönergesi dizin listelemesi için kullanılacak biçembent dosyasının ismini belirtmek için kullanılır.

IndexStyleSheet "/css/style.css"

Bu yönergenin IndexOptions HTMLTable ile birlikte kullanılması sonuçlanan HTML dosyasına bir miktar CSS sınıfı ekler. Tablonun tamamı indexlist için bir CSS kimliği verir ve aşağıdaki sınıflar listenin çeşitli parçalarıyla ilişkilendirilir:

Sınıf | Tanım
tr.indexhead | Liste satırının başlığı
th.indexcolicon and td.indexcolicon | Simge sütunu
th.indexcolname and td.indexcolname | Dosya ismi sütunu
th.indexcollastmod and td.indexcollastmod | Son değişiklik sütunu
th.indexcolsize and td.indexcolsize | Dosya boyutu sütunu
th.indexcoldesc and td.indexcoldesc | Açıklama sütunu
tr.breakrow | Tablonun altınaki yatay çizgi
tr.odd and tr.even | Tek ve çift satırlar

ReadmeName Yönergesi

Açıklama: | Dizin listesinin sonuna yerleştirilecek dosyanın ismini belirler.
Sözdizimi: | ReadmeName dosya-ismi
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_autoindex

ReadmeName yönergesi dizin listesinin sonuna eklenecek dosyanın ismini belirler. dosya-ismi ile listeye dahil edilecek dosyanın ismi listelenen dizine göreli olarak belirtilir. Eğer dosya ismi 2. örnekteki gibi bir bölü çizgisi ile başlıyorsa DocumentRoot’a göreli belirtildiği varsayılır.

# 1. Örnek
ReadmeName FOOTER.html
# 2. Örnek
ReadmeName /include/FOOTER.html

Ayrıca bu davranışın daha ayrıntılı ele alındığı HeaderName yönergesine de bakınız.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_buffer - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_buffer

Description: | Support for request buffering
Status: | Extension
Module Identifier: | buffer_module
Source File: | mod_buffer.c
Compatibility: | Available in Apache 2.3 and later

Summary

This module provides the ability to buffer the input and output filter stacks.

Under certain circumstances, content generators might create content in small chunks. In order to promote memory reuse, in memory chunks are always 8k in size, regardless of the size of the chunk itself. When many small chunks are generated by a request, this can create a large memory footprint while the request is being processed, and an unnecessarily large amount of data on the wire. The addition of a buffer collapses the response into the fewest chunks possible.

When httpd is used in front of an expensive content generator, buffering the response may allow the backend to complete processing and release resources sooner, depending on how the backend is designed.

The buffer filter may be added to either the input or the output filter stacks, as appropriate, using the SetInputFilter, SetOutputFilter, AddOutputFilter or AddOutputFilterByType directives.

Using buffer with mod_include

AddOutputFilterByType INCLUDES;BUFFER text/html
The buffer filters read the request/response into RAM and then repack the request/response into the fewest memory buckets possible, at the cost of CPU time. When the request/response is already efficiently packed, buffering the request/response could cause the request/response to be slower than not using a buffer at all. These filters should be used with care, and only where necessary.

See also

  • Filters

BufferSize Directive

Description: | Maximum size in bytes to buffer by the buffer filter
Syntax: | BufferSize integer
Default: | BufferSize 131072
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_buffer

The BufferSize directive specifies the amount of data in bytes that will be buffered before being read from or written to each request. The default is 128 kilobytes.


mod_cache - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cache

Description: | RFC 2616 compliant HTTP caching filter.
Status: | Extension
Module Identifier: | cache_module
Source File: | mod_cache.c

Summary

This module should be used with care, as when the CacheQuickHandler directive is in its default value of on, the Allow and Deny directives will be circumvented. You should not enable quick handler caching for any content to which you wish to limit access by client host name, address or environment variable.

mod_cache implements an RFC 2616 compliant HTTP content caching filter, with support for the caching of content negotiated responses containing the Vary header.

RFC 2616 compliant caching provides a mechanism to verify whether stale or expired content is still fresh, and can represent a significant performance boost when the origin server supports conditional requests by honouring the If-None-Match HTTP request header. Content is only regenerated from scratch when the content has changed, and not when the cached entry expires.

As a filter, mod_cache can be placed in front of content originating from any handler, including flat files (served from a slow disk cached on a fast disk), the output of a CGI script or dynamic content generator, or content proxied from another server.

In the default configuration, mod_cache inserts the caching filter as far forward as possible within the filter stack, utilising the quick handler to bypass all per request processing when returning content to the client. In this mode of operation, mod_cache may be thought of as a caching proxy server bolted to the front of the webserver, while running within the webserver itself.

When the quick handler is switched off using the CacheQuickHandler directive, it becomes possible to insert the CACHE filter at a point in the filter stack chosen by the administrator. This provides the opportunity to cache content before that content is personalised by the mod_include filter, or optionally compressed by the mod_deflate filter.

Under normal operation, mod_cache will respond to and can be controlled by the Cache-Control and Pragma headers sent from a client in a request, or from a server within a response. Under exceptional circumstances, mod_cache can be configured to override these headers and force site specific behaviour, however such behaviour will be limited to this cache only, and will not affect the operation of other caches that may exist between the client and server, and as a result is not recommended unless strictly necessary.

RFC 2616 allows for the cache to return stale data while the existing stale entry is refreshed from the origin server, and this is supported by mod_cache when the CacheLock directive is suitably configured. Such responses will contain a Warning HTTP header with a 110 response code. RFC 2616 also allows a cache to return stale data when the attempt made to refresh the stale data returns an error 500 or above, and this behaviour is supported by default by mod_cache. Such responses will contain a Warning HTTP header with a 111 response code.

mod_cache requires the services of one or more storage management modules. The following storage management modules are included in the base Apache distribution:

mod_cache_disk
Implements a disk based storage manager. Headers and bodies are stored separately on disk, in a directory structure derived from the md5 hash of the cached URL. Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not supported by this module. The htcacheclean tool is provided to list cached URLs, remove cached URLs, or to maintain the size of the disk cache within size and inode limits.
mod_cache_socache
Implements a shared object cache based storage manager. Headers and bodies are stored together beneath a single key based on the URL of the response being cached. Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not supported by this module.

Further details, discussion, and examples, are provided in the Caching Guide.

See also

  • Caching Guide

Related Modules and Directives

Related Modules Related Directives
  • mod_cache_disk
  • mod_cache_socache
  • CacheRoot
  • CacheDirLevels
  • CacheDirLength
  • CacheMinFileSize
  • CacheMaxFileSize
  • CacheSocache
  • CacheSocacheMaxTime
  • CacheSocacheMinTime
  • CacheSocacheMaxSize
  • CacheSocacheReadSize
  • CacheSocacheReadTime

Sample Configuration

Sample httpd.conf

#
# Sample Cache Configuration
#
LoadModule cache_module modules/mod_cache.so
<IfModule mod_cache.c>
    LoadModule cache_disk_module modules/mod_cache_disk.so
    <IfModule mod_cache_disk.c>
        CacheRoot "c:/cacheroot"
        CacheEnable disk  "/"
        CacheDirLevels 5
        CacheDirLength 3
    </IfModule>

    # When acting as a proxy, don't cache the list of security updates
    CacheDisable "http://security.update.server/update-list/"
</IfModule>

Avoiding the Thundering Herd

When a cached entry becomes stale, mod_cache will submit a conditional request to the backend, which is expected to confirm whether the cached entry is still fresh, and send an updated entity if not.

A small but finite amount of time exists between the time the cached entity becomes stale, and the time the stale entity is fully refreshed. On a busy server, a significant number of requests might arrive during this time, and cause a thundering herd of requests to strike the backend suddenly and unpredictably.

To keep the thundering herd at bay, the CacheLock directive can be used to define a directory in which locks are created for URLs in flight. The lock is used as a hint by other requests to either suppress an attempt to cache (someone else has gone to fetch the entity), or to indicate that a stale entry is being refreshed (stale content will be returned in the mean time).

Initial caching of an entry

When an entity is cached for the first time, a lock will be created for the entity until the response has been fully cached. During the lifetime of the lock, the cache will suppress the second and subsequent attempt to cache the same entity. While this doesn't hold back the thundering herd, it does stop the cache attempting to cache the same entity multiple times simultaneously.

Refreshment of a stale entry

When an entity reaches its freshness lifetime and becomes stale, a lock will be created for the entity until the response has either been confirmed as still fresh, or replaced by the backend. During the lifetime of the lock, the second and subsequent incoming request will cause stale data to be returned, and the thundering herd is kept at bay.

Locks and Cache-Control: no-cache

Locks are used as a hint only to enable the cache to be more gentle on backend servers, however the lock can be overridden if necessary. If the client sends a request with a Cache-Control header forcing a reload, any lock that may be present will be ignored, and the client's request will be honored immediately and the cached entry refreshed.

As a further safety mechanism, locks have a configurable maximum age. Once this age has been reached, the lock is removed, and a new request is given the opportunity to create a new lock. This maximum age can be set using the CacheLockMaxAge directive, and defaults to 5 seconds.

Example configuration

Enabling the cache lock

#
# Enable the cache lock
#
<IfModule mod_cache.c>
    CacheLock on
    CacheLockPath "/tmp/mod_cache-lock"
    CacheLockMaxAge 5
</IfModule>

Fine Control with the CACHE Filter

Under the default mode of cache operation, the cache runs as a quick handler, short circuiting the majority of server processing and offering the highest cache performance available.

In this mode, the cache bolts onto the front of the server, acting as if a free standing RFC 2616 caching proxy had been placed in front of the server.

While this mode offers the best performance, the administrator may find that under certain circumstances they may want to perform further processing on the request after the request is cached, such as to inject personalisation into the cached page, or to apply authorisation restrictions to the content. Under these circumstances, an administrator is often forced to place independent reverse proxy servers either behind or in front of the caching server to achieve this.

To solve this problem the CacheQuickHandler directive can be set to off, and the server will process all phases normally handled by a non-cached request, including the authentication and authorisation phases.

In addition, the administrator may optionally specify the precise point within the filter chain where caching is to take place by adding the CACHE filter to the output filter chain.

For example, to cache content before applying compression to the response, place the CACHE filter before the DEFLATE filter as in the example below:

# Cache content before optional compression
CacheQuickHandler off
AddOutputFilterByType CACHE;DEFLATE text/plain

Another option is to have content cached before personalisation is applied by mod_include (or another content processing filter). In this example templates containing tags understood by mod_include are cached before being parsed:

# Cache content before mod_include and mod_deflate
CacheQuickHandler off
AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

You may place the CACHE filter anywhere you wish within the filter chain. In this example, content is cached after being parsed by mod_include, but before being processed by mod_deflate:

# Cache content between mod_include and mod_deflate
CacheQuickHandler off
AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html

Warning:

If the location of the CACHE filter in the filter chain is changed for any reason, you may need to flush your cache to ensure that your data served remains consistent. mod_cache is not in a position to enforce this for you.

Cache Status and Logging

Once mod_cache has made a decision as to whether or not an entity is to be served from cache, the detailed reason for the decision is written to the subprocess environment within the request under the cache-status key. This reason can be logged by the LogFormat directive as follows:

LogFormat "%{cache-status}e ..."

Based on the caching decision made, the reason is also written to the subprocess environment under one the following four keys, as appropriate:

cache-hit
The response was served from cache.
cache-revalidate
The response was stale and was successfully revalidated, then served from cache.
cache-miss
The response was served from the upstream server.
cache-invalidate
The cached entity was invalidated by a request method other than GET or HEAD.

This makes it possible to support conditional logging of cached requests as per the following example:

CustomLog "cached-requests.log" common env=cache-hit
CustomLog "uncached-requests.log" common env=cache-miss
CustomLog "revalidated-requests.log" common env=cache-revalidate
CustomLog "invalidated-requests.log" common env=cache-invalidate

For module authors, a hook called cache_status is available, allowing modules to respond to the caching outcomes above in customised ways.

CacheDefaultExpire Directive

Description: | The default duration to cache a document when no expiry date is specified.
Syntax: | CacheDefaultExpire seconds
Default: | CacheDefaultExpire 3600 (one hour)
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

The CacheDefaultExpire directive specifies a default time, in seconds, to cache a document if neither an expiry date nor last-modified date are provided with the document. The value specified with the CacheMaxExpire directive does not override this setting.

CacheDefaultExpire 86400

CacheDetailHeader Directive

Description: | Add an X-Cache-Detail header to the response.
Syntax: | CacheDetailHeader on|off
Default: | CacheDetailHeader off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache
Compatibility: | Available in Apache 2.3.9 and later

When the CacheDetailHeader directive is switched on, an X-Cache-Detail header will be added to the response containing the detailed reason for a particular caching decision.

It can be useful during development of cached RESTful services to have additional information about the caching decision written to the response headers, so as to confirm whether Cache-Control and other headers have been correctly used by the service and client.

If the normal handler is used, this directive may appear within a <Directory> or <Location> directive. If the quick handler is used, this directive must appear within a server or virtual host context, otherwise the setting will be ignored.

# Enable the X-Cache-Detail header
CacheDetailHeader on

X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost

CacheDisable Directive

Description: | Disable caching of specified URLs
Syntax: | CacheDisable url-string | on
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

The CacheDisable directive instructs mod_cache to not cache urls at or below url-string.

Example

CacheDisable "/local_files"

If used in a <Location> directive, the path needs to be specified below the Location, or if the word "on" is used, caching for the whole location will be disabled.

Example

<Location "/foo">
    CacheDisable on
</Location>

The no-cache environment variable can be set to disable caching on a finer grained set of resources in versions 2.2.12 and later.

See also

  • Environment Variables in Apache

CacheEnable Directive

Description: | Enable caching of specified URLs using a specified storage manager
Syntax: | CacheEnable cache_type [url-string]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_cache
Compatibility: | A url-string of '/' applied to forward proxy content in 2.2 and earlier.

The CacheEnable directive instructs mod_cache to cache urls at or below url-string. The cache storage manager is specified with the cache_type argument. The CacheEnable directive can alternatively be placed inside either <Location> or <LocationMatch> sections to indicate the content is cacheable. cache_type disk instructs mod_cache to use the disk based storage manager implemented by mod_cache_disk. cache_type socache instructs mod_cache to use the shared object cache based storage manager implemented by mod_cache_socache.

In the event that the URL space overlaps between different CacheEnable directives (as in the example below), each possible storage manager will be run until the first one that actually processes the request. The order in which the storage managers are run is determined by the order of the CacheEnable directives in the configuration file. CacheEnable directives within <Location> or <LocationMatch> sections are processed before globally defined CacheEnable directives.

When acting as a forward proxy server, url-string must minimally begin with a protocol for which caching should be enabled.

# Cache content (normal handler only)
CacheQuickHandler off
<Location "/foo">
    CacheEnable disk
</Location>

# Cache regex (normal handler only)
CacheQuickHandler off
<LocationMatch "foo$">
    CacheEnable disk
</LocationMatch>

# Cache all but forward proxy url's (normal or quick handler)
CacheEnable  disk  /

# Cache FTP-proxied url's (normal or quick handler)
CacheEnable  disk  ftp://

# Cache forward proxy content from www.example.org (normal or quick handler)
CacheEnable  disk  http://www.example.org/

A hostname starting with a "*" matches all hostnames with that suffix. A hostname starting with "." matches all hostnames containing the domain components that follow.

# Match www.example.org, and fooexample.org
CacheEnable  disk  "http://*example.org/"
# Match www.example.org, but not fooexample.org
CacheEnable  disk  "http://.example.org/"

The no-cache environment variable can be set to disable caching on a finer grained set of resources in versions 2.2.12 and later.

See also

  • Environment Variables in Apache

CacheHeader Directive

Description: | Add an X-Cache header to the response.
Syntax: | CacheHeader on|off
Default: | CacheHeader off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache
Compatibility: | Available in Apache 2.3.9 and later

When the CacheHeader directive is switched on, an X-Cache header will be added to the response with the cache status of this response. If the normal handler is used, this directive may appear within a <Directory> or <Location> directive. If the quick handler is used, this directive must appear within a server or virtual host context, otherwise the setting will be ignored.

HIT
The entity was fresh, and was served from cache.
REVALIDATE
The entity was stale, was successfully revalidated and was served from cache.
MISS
The entity was fetched from the upstream server and was not served from cache.
# Enable the X-Cache header
CacheHeader on
X-Cache: HIT from localhost

CacheIgnoreCacheControl Directive

Description: | Ignore request to not serve cached content to client
Syntax: | CacheIgnoreCacheControl On|Off
Default: | CacheIgnoreCacheControl Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

Ordinarily, requests containing a Cache-Control: no-cache or Pragma: no-cache header value will not be served from the cache. The CacheIgnoreCacheControl directive allows this behavior to be overridden. CacheIgnoreCacheControl On tells the server to attempt to serve the resource from the cache even if the request contains no-cache header values. Resources requiring authorization will never be cached.

CacheIgnoreCacheControl On

Warning:

This directive will allow serving from the cache even if the client has requested that the document not be served from the cache. This might result in stale content being served.

See also

  • CacheStorePrivate
  • CacheStoreNoStore

CacheIgnoreHeaders Directive

Description: | Do not store the given HTTP header(s) in the cache.
Syntax: | CacheIgnoreHeaders header-string [header-string] ...
Default: | CacheIgnoreHeaders None
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

According to RFC 2616, hop-by-hop HTTP headers are not stored in the cache. The following HTTP headers are hop-by-hop headers and thus do not get stored in the cache in any case regardless of the setting of CacheIgnoreHeaders:

  • Connection
  • Keep-Alive
  • Proxy-Authenticate
  • Proxy-Authorization
  • TE
  • Trailers
  • Transfer-Encoding
  • Upgrade

CacheIgnoreHeaders specifies additional HTTP headers that should not to be stored in the cache. For example, it makes sense in some cases to prevent cookies from being stored in the cache.

CacheIgnoreHeaders takes a space separated list of HTTP headers that should not be stored in the cache. If only hop-by-hop headers not should be stored in the cache (the RFC 2616 compliant behaviour), CacheIgnoreHeaders can be set to None.

Example 1

CacheIgnoreHeaders Set-Cookie

Example 2

CacheIgnoreHeaders None

Warning:

If headers like Expires which are needed for proper cache management are not stored due to a CacheIgnoreHeaders setting, the behaviour of mod_cache is undefined.

CacheIgnoreNoLastMod Directive

Description: | Ignore the fact that a response has no Last Modified header.
Syntax: | CacheIgnoreNoLastMod On|Off
Default: | CacheIgnoreNoLastMod Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

Ordinarily, documents without a last-modified date are not cached. Under some circumstances the last-modified date is removed (during mod_include processing for example) or not provided at all. The CacheIgnoreNoLastMod directive provides a way to specify that documents without last-modified dates should be considered for caching, even without a last-modified date. If neither a last-modified date nor an expiry date are provided with the document then the value specified by the CacheDefaultExpire directive will be used to generate an expiration date.

CacheIgnoreNoLastMod On

CacheIgnoreQueryString Directive

Description: | Ignore query string when caching
Syntax: | CacheIgnoreQueryString On|Off
Default: | CacheIgnoreQueryString Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

Ordinarily, requests with query string parameters are cached separately for each unique query string. This is according to RFC 2616/13.9 done only if an expiration time is specified. The CacheIgnoreQueryString directive tells the cache to cache requests even if no expiration time is specified, and to reply with a cached reply even if the query string differs. From a caching point of view the request is treated as if having no query string when this directive is enabled.

CacheIgnoreQueryString On

CacheIgnoreURLSessionIdentifiers Directive

Description: | Ignore defined session identifiers encoded in the URL when caching
Syntax: | CacheIgnoreURLSessionIdentifiers identifier [identifier] ...
Default: | CacheIgnoreURLSessionIdentifiers None
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

Sometimes applications encode the session identifier into the URL like in the following Examples:

  • /someapplication/image.gif;jsessionid=123456789
  • /someapplication/image.gif?PHPSESSIONID=12345678

This causes cachable resources to be stored separately for each session, which is often not desired. CacheIgnoreURLSessionIdentifiers lets define a list of identifiers that are removed from the key that is used to identify an entity in the cache, such that cachable resources are not stored separately for each session.

CacheIgnoreURLSessionIdentifiers None clears the list of ignored identifiers. Otherwise, each identifier is added to the list.

Example 1

CacheIgnoreURLSessionIdentifiers jsessionid

Example 2

CacheIgnoreURLSessionIdentifiers None

CacheKeyBaseURL Directive

Description: | Override the base URL of reverse proxied cache keys.
Syntax: | CacheKeyBaseURL URL
Default: | CacheKeyBaseURL http://example.com
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache
Compatibility: | Available in Apache 2.3.9 and later

When the CacheKeyBaseURL directive is specified, the URL provided will be used as the base URL to calculate the URL of the cache keys in the reverse proxy configuration. When not specified, the scheme, hostname and port of the current virtual host is used to construct the cache key. When a cluster of machines is present, and all cached entries should be cached beneath the same cache key, a new base URL can be specified with this directive.

# Override the base URL of the cache key.
CacheKeyBaseURL "http://www.example.com/"
Take care when setting this directive. If two separate virtual hosts are accidentally given the same base URL, entries from one virtual host will be served to the other.

CacheLastModifiedFactor Directive

Description: | The factor used to compute an expiry date based on the LastModified date.
Syntax: | CacheLastModifiedFactor float
Default: | CacheLastModifiedFactor 0.1
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

In the event that a document does not provide an expiry date but does provide a last-modified date, an expiry date can be calculated based on the time since the document was last modified. The CacheLastModifiedFactor directive specifies a factor to be used in the generation of this expiry date according to the following formula: expiry-period = time-since-last-modified-date * factor expiry-date = current-date + expiry-period For example, if the document was last modified 10 hours ago, and factor is 0.1 then the expiry-period will be set to 10*0.1 = 1 hour. If the current time was 3:00pm then the computed expiry-date would be 3:00pm + 1hour = 4:00pm. If the expiry-period would be longer than that set by CacheMaxExpire, then the latter takes precedence.

CacheLastModifiedFactor 0.5

CacheLock Directive

Description: | Enable the thundering herd lock.
Syntax: | CacheLock on|off
Default: | CacheLock off
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache
Compatibility: | Available in Apache 2.2.15 and later

The CacheLock directive enables the thundering herd lock for the given URL space.

In a minimal configuration the following directive is all that is needed to enable the thundering herd lock in the default system temp directory.

# Enable cache lock
CacheLock on

CacheLockMaxAge Directive

Description: | Set the maximum possible age of a cache lock.
Syntax: | CacheLockMaxAge integer
Default: | CacheLockMaxAge 5
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

The CacheLockMaxAge directive specifies the maximum age of any cache lock.

A lock older than this value in seconds will be ignored, and the next incoming request will be given the opportunity to re-establish the lock. This mechanism prevents a slow client taking an excessively long time to refresh an entity.

CacheLockPath Directive

Description: | Set the lock path directory.
Syntax: | CacheLockPath directory
Default: | CacheLockPath /tmp/mod_cache-lock
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache

The CacheLockPath directive allows you to specify the directory in which the locks are created. By default, the system's temporary folder is used. Locks consist of empty files that only exist for stale URLs in flight, so is significantly less resource intensive than the traditional disk cache.

CacheMaxExpire Directive

Description: | The maximum time in seconds to cache a document
Syntax: | CacheMaxExpire seconds
Default: | CacheMaxExpire 86400 (one day)
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

The CacheMaxExpire directive specifies the maximum number of seconds for which cachable HTTP documents will be retained without checking the origin server. Thus, documents will be out of date at most this number of seconds. This maximum value is enforced even if an expiry date was supplied with the document.

CacheMaxExpire 604800

CacheMinExpire Directive

Description: | The minimum time in seconds to cache a document
Syntax: | CacheMinExpire seconds
Default: | CacheMinExpire 0
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

The CacheMinExpire directive specifies the minimum number of seconds for which cachable HTTP documents will be retained without checking the origin server. This is only used if no valid expire time was supplied with the document.

CacheMinExpire 3600

CacheQuickHandler Directive

Description: | Run the cache from the quick handler.
Syntax: | CacheQuickHandler on|off
Default: | CacheQuickHandler on
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache
Compatibility: | Apache HTTP Server 2.3.3 and later

The CacheQuickHandler directive controls the phase in which the cache is handled.

In the default enabled configuration, the cache operates within the quick handler phase. This phase short circuits the majority of server processing, and represents the most performant mode of operation for a typical server. The cache bolts onto the front of the server, and the majority of server processing is avoided.

When disabled, the cache operates as a normal handler, and is subject to the full set of phases when handling a server request. While this mode is slower than the default, it allows the cache to be used in cases where full processing is required, such as when content is subject to authorisation.

# Run cache as a normal handler
CacheQuickHandler off

It is also possible, when the quick handler is disabled, for the administrator to choose the precise location within the filter chain where caching is to be performed, by adding the CACHE filter to the chain.

# Cache content before mod_include and mod_deflate
CacheQuickHandler off
AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

If the CACHE filter is specified more than once, the last instance will apply.

CacheStaleOnError Directive

Description: | Serve stale content in place of 5xx responses.
Syntax: | CacheStaleOnError on|off
Default: | CacheStaleOnError on
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache
Compatibility: | Available in Apache 2.3.9 and later

When the CacheStaleOnError directive is switched on, and when stale data is available in the cache, the cache will respond to 5xx responses from the backend by returning the stale data instead of the 5xx response. While the Cache-Control headers sent by clients will be respected, and the raw 5xx responses returned to the client on request, the 5xx response so returned to the client will not invalidate the content in the cache.

# Serve stale data on error.
CacheStaleOnError on

CacheStoreExpired Directive

Description: | Attempt to cache responses that the server reports as expired
Syntax: | CacheStoreExpired On|Off
Default: | CacheStoreExpired Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

Since httpd 2.2.4, responses which have already expired are not stored in the cache. The CacheStoreExpired directive allows this behavior to be overridden. CacheStoreExpired On tells the server to attempt to cache the resource if it is stale. Subsequent requests would trigger an If-Modified-Since request of the origin server, and the response may be fulfilled from cache if the backend resource has not changed.

CacheStoreExpired On

CacheStoreNoStore Directive

Description: | Attempt to cache requests or responses that have been marked as no-store.
Syntax: | CacheStoreNoStore On|Off
Default: | CacheStoreNoStore Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

Ordinarily, requests or responses with Cache-Control: no-store header values will not be stored in the cache. The CacheStoreNoStore directive allows this behavior to be overridden. CacheStoreNoStore On tells the server to attempt to cache the resource even if it contains no-store header values. Resources requiring authorization will never be cached.

CacheStoreNoStore On

Warning:

As described in RFC 2616, the no-store directive is intended to "prevent the inadvertent release or retention of sensitive information (for example, on backup tapes)." Enabling this option could store sensitive information in the cache. You are hereby warned.

See also

  • CacheIgnoreCacheControl
  • CacheStorePrivate

CacheStorePrivate Directive

Description: | Attempt to cache responses that the server has marked as private
Syntax: | CacheStorePrivate On|Off
Default: | CacheStorePrivate Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache

Ordinarily, responses with Cache-Control: private header values will not be stored in the cache. The CacheStorePrivate directive allows this behavior to be overridden. CacheStorePrivate On tells the server to attempt to cache the resource even if it contains private header values. Resources requiring authorization will never be cached.

CacheStorePrivate On

Warning:

This directive will allow caching even if the upstream server has requested that the resource not be cached. This directive is only ideal for a 'private' cache.

See also

  • CacheIgnoreCacheControl
  • CacheStoreNoStore


mod_cache_disk - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cache_disk

Description: | Disk based storage module for the HTTP caching filter.
Status: | Extension
Module Identifier: | cache_disk_module
Source File: | mod_cache_disk.c

Summary

mod_cache_disk implements a disk based storage manager for mod_cache.

The headers and bodies of cached responses are stored separately on disk, in a directory structure derived from the md5 hash of the cached URL.

Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not yet supported by this module.

Atomic cache updates to both header and body files are achieved without the need for locking by storing the device and inode numbers of the body file within the header file. This has the side effect that cache entries manually moved into the cache will be ignored.

The htcacheclean tool is provided to list cached URLs, remove cached URLs, or to maintain the size of the disk cache within size and/or inode limits. The tool can be run on demand, or can be daemonized to offer continuous monitoring of directory sizes.

Note:

mod_cache_disk requires the services of mod_cache, which must be loaded before mod_cache_disk.

Note:

mod_cache_disk uses the sendfile feature to serve files from the cache when supported by the platform, and when enabled with EnableSendfile. However, per-directory and .htaccess configuration of EnableSendfile are ignored by mod_cache_disk as the corresponding settings are not available to the module when a request is being served from the cache.

See also

  • mod_cache
  • mod_cache_socache
  • Caching Guide

CacheDirLength Directive

Description: | The number of characters in subdirectory names
Syntax: | CacheDirLength length
Default: | CacheDirLength 2
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache_disk

The CacheDirLength directive sets the number of characters for each subdirectory name in the cache hierarchy. It can be used in conjunction with CacheDirLevels to determine the approximate structure of your cache hierarchy.

A high value for CacheDirLength combined with a low value for CacheDirLevels will result in a relatively flat hierarchy, with a large number of subdirectories at each level.

The result of CacheDirLevels* CacheDirLength must not be higher than 20.

CacheDirLevels Directive

Description: | The number of levels of subdirectories in the cache.
Syntax: | CacheDirLevels levels
Default: | CacheDirLevels 2
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache_disk

The CacheDirLevels directive sets the number of subdirectory levels in the cache. Cached data will be saved this many directory levels below the CacheRoot directory.

A high value for CacheDirLevels combined with a low value for CacheDirLength will result in a relatively deep hierarchy, with a small number of subdirectories at each level.

The result of CacheDirLevels* CacheDirLength must not be higher than 20.

CacheMaxFileSize Directive

Description: | The maximum size (in bytes) of a document to be placed in the cache
Syntax: | CacheMaxFileSize bytes
Default: | CacheMaxFileSize 1000000
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_disk

The CacheMaxFileSize directive sets the maximum size, in bytes, for a document to be considered for storage in the cache.

CacheMaxFileSize 64000

CacheMinFileSize Directive

Description: | The minimum size (in bytes) of a document to be placed in the cache
Syntax: | CacheMinFileSize bytes
Default: | CacheMinFileSize 1
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_disk

The CacheMinFileSize directive sets the minimum size, in bytes, for a document to be considered for storage in the cache.

CacheMinFileSize 64

CacheReadSize Directive

Description: | The minimum size (in bytes) of the document to read and be cached before sending the data downstream
Syntax: | CacheReadSize bytes
Default: | CacheReadSize 0
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_disk

The CacheReadSize directive sets the minimum amount of data, in bytes, to be read from the backend before the data is sent to the client. The default of zero causes all data read of any size to be passed downstream to the client immediately as it arrives. Setting this to a higher value causes the disk cache to buffer at least this amount before sending the result to the client. This can improve performance when caching content from a reverse proxy.

This directive only takes effect when the data is being saved to the cache, as opposed to data being served from the cache.

CacheReadSize 102400

CacheReadTime Directive

Description: | The minimum time (in milliseconds) that should elapse while reading before data is sent downstream
Syntax: | CacheReadTime milliseconds
Default: | CacheReadTime 0
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_disk

The CacheReadTime directive sets the minimum amount of elapsed time that should pass before making an attempt to send data downstream to the client. During the time period, data will be buffered before sending the result to the client. This can improve performance when caching content from a reverse proxy.

The default of zero disables this option.

This directive only takes effect when the data is being saved to the cache, as opposed to data being served from the cache. It is recommended that this option be used alongside the CacheReadSize directive to ensure that the server does not buffer excessively should data arrive faster than expected.

CacheReadTime 1000

CacheRoot Directive

Description: | The directory root under which cache files are stored
Syntax: | CacheRoot directory
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache_disk

The CacheRoot directive defines the name of the directory on the disk to contain cache files. If the mod_cache_disk module has been loaded or compiled in to the Apache server, this directive must be defined. Failing to provide a value for CacheRoot will result in a configuration file processing error. The CacheDirLevels and CacheDirLength directives define the structure of the directories under the specified root directory.

CacheRoot c:/cacheroot

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_cache_socache - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cache_socache

Description: | Shared object cache (socache) based storage module for the HTTP caching filter.
Status: | Extension
Module Identifier: | cache_socache_module
Source File: | mod_cache_socache.c

Summary

mod_cache_socache implements a shared object cache (socache) based storage manager for mod_cache.

The headers and bodies of cached responses are combined, and stored underneath a single key in the shared object cache. A number of implementations of shared object caches are available to choose from.

Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not yet supported by this module.

# Turn on caching
CacheSocache shmcb
CacheSocacheMaxSize 102400
<Location /foo>
    CacheEnable socache
</Location>

# Fall back to the disk cache
CacheSocache shmcb
CacheSocacheMaxSize 102400
<Location /foo>
    CacheEnable socache
    CacheEnable disk
</Location>

Note:

mod_cache_socache requires the services of mod_cache, which must be loaded before mod_cache_socache.

See also

  • mod_cache
  • mod_cache_disk
  • Caching Guide

CacheSocache Directive

Description: | The shared object cache implementation to use
Syntax: | CacheSocache type[:args]
Context: | server config, virtual host
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocache directive defines the name of the shared object cache implementation to use, followed by optional arguments for that implementation. A number of implementations of shared object caches are available to choose from.

CacheSocache shmcb

CacheSocacheMaxSize Directive

Description: | The maximum size (in bytes) of an entry to be placed in the cache
Syntax: | CacheSocacheMaxSize bytes
Default: | CacheSocacheMaxSize 102400
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocacheMaxSize directive sets the maximum size, in bytes, for the combined headers and body of a document to be considered for storage in the cache. The larger the headers that are stored alongside the body, the smaller the body may be.

The mod_cache_socache module will only attempt to cache responses that have an explicit content length, or that are small enough to be written in one pass. This is done to allow the mod_cache_disk module to have an opportunity to cache responses larger than those cacheable within mod_cache_socache.

CacheSocacheMaxSize 102400

CacheSocacheMaxTime Directive

Description: | The maximum time (in seconds) for a document to be placed in the cache
Syntax: | CacheSocacheMaxTime seconds
Default: | CacheSocacheMaxTime 86400
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocacheMaxTime directive sets the maximum freshness lifetime, in seconds, for a document to be stored in the cache. This value overrides the freshness lifetime defined for the document by the HTTP protocol.

CacheSocacheMaxTime 86400

CacheSocacheMinTime Directive

Description: | The minimum time (in seconds) for a document to be placed in the cache
Syntax: | CacheSocacheMinTime seconds
Default: | CacheSocacheMinTime 600
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocacheMinTime directive sets the amount of seconds beyond the freshness lifetime of the response that the response should be cached for in the shared object cache. If a response is only stored for its freshness lifetime, there will be no opportunity to revalidate the response to make it fresh again.

CacheSocacheMinTime 600

CacheSocacheReadSize Directive

Description: | The minimum size (in bytes) of the document to read and be cached before sending the data downstream
Syntax: | CacheSocacheReadSize bytes
Default: | CacheSocacheReadSize 0
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocacheReadSize directive sets the minimum amount of data, in bytes, to be read from the backend before the data is sent to the client. The default of zero causes all data read of any size to be passed downstream to the client immediately as it arrives. Setting this to a higher value causes the disk cache to buffer at least this amount before sending the result to the client. This can improve performance when caching content from a slow reverse proxy.

This directive only takes effect when the data is being saved to the cache, as opposed to data being served from the cache.

CacheReadSize 102400

CacheSocacheReadTime Directive

Description: | The minimum time (in milliseconds) that should elapse while reading before data is sent downstream
Syntax: | CacheSocacheReadTime milliseconds
Default: | CacheSocacheReadTime 0
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_cache_socache
Compatibility: | Available in Apache 2.4.5 and later

The CacheSocacheReadTime directive sets the minimum amount of elapsed time that should pass before making an attempt to send data downstream to the client. During the time period, data will be buffered before sending the result to the client. This can improve performance when caching content from a reverse proxy.

The default of zero disables this option.

This directive only takes effect when the data is being saved to the cache, as opposed to data being served from the cache. It is recommended that this option be used alongside the CacheSocacheReadSize directive to ensure that the server does not buffer excessively should data arrive faster than expected.

CacheSocacheReadTime 1000

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_cern_meta - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cern_meta

Description: | CERN httpd metafile semantics
Status: | Extension
Module Identifier: | cern_meta_module
Source File: | mod_cern_meta.c

Summary

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.

More information on the CERN metafile semantics is available.

See also

  • mod_headers
  • mod_asis

MetaDir Directive

Description: | Name of the directory to find CERN-style meta information files
Syntax: | MetaDir directory
Default: | MetaDir .web
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

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 "." to look in the same directory as the file:

MetaDir .

Or, to set it to a subdirectory of the directory containing the files:

MetaDir .meta

MetaFiles Directive

Description: | Activates CERN meta-file processing
Syntax: | MetaFiles on|off
Default: | MetaFiles off
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

Turns on/off Meta file processing on a per-directory basis.

MetaSuffix Directive

Description: | File name suffix for the file containing CERN-style meta information
Syntax: | MetaSuffix suffix
Default: | MetaSuffix .meta
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

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 DOCUMENT_ROOT/somedir/index.html to look in DOCUMENT_ROOT/somedir/.web/index.html.meta and will use its contents to generate additional MIME header information.

Example:

MetaSuffix .meta

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_cgi - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cgi

Description: | Execution of CGI scripts
Status: | Base
Module Identifier: | cgi_module
Source File: | mod_cgi.c

Summary

Any file that has the handler cgi-script will be treated as a CGI script, and run by the server, with its output being returned to the client. Files acquire this handler either by having a name containing an extension defined by the AddHandler directive, or by being in a ScriptAlias directory.

For an introduction to using CGI scripts with Apache, see our tutorial on Dynamic Content With CGI.

When using a multi-threaded MPM under unix, the module mod_cgid should be used in place of this module. At the user level, the two modules are essentially identical.

For backward-compatibility, the cgi-script handler will also be activated for any file with the mime-type application/x-httpd-cgi. The use of the magic mime-type is deprecated.

See also

  • AcceptPathInfo
  • Options ExecCGI
  • ScriptAlias
  • AddHandler
  • Running CGI programs under different user IDs
  • CGI Specification

CGI Environment variables

The server will set the CGI environment variables as described in the CGI specification, with the following provisions:

PATH_INFO
This will not be available if the AcceptPathInfo directive is explicitly set to off. 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 On for mod_cgi requests.
REMOTE_HOST
This will only be set if HostnameLookups is set to on (it is off by default), and if a reverse DNS lookup of the accessing host's address indeed finds a host name.
REMOTE_IDENT
This will only be set if IdentityCheck is set to on 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.
REMOTE_USER
This will only be set if the CGI script is subject to authentication.

This module also leverages the core functions ap_add_common_vars and ap_add_cgi_vars to add environment variables like:

DOCUMENT_ROOT
Set with the content of the related DocumentRoot directive.
SERVER_NAME
The fully qualified domain name related to the request.
SERVER_ADDR
The IP address of the Virtual Host serving the request.
SERVER_ADMIN
Set with the content of the related ServerAdmin directive.

For an exhaustive list it is suggested to write a basic CGI script that dumps all the environment variables passed by Apache in a convenient format.

CGI Debugging

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 provide more detailed logging of errors when they occur.

CGI Logfile Format

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:

%% [time] request-line
%% HTTP-status CGI-script-filename

If the error is that CGI script cannot be run, the log file will contain an extra two lines:

%%error
error-message

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:

%request
All HTTP request headers received
POST or PUT entity (if any)
%response
All headers output by the CGI script
%stdout
CGI standard output
%stderr
CGI standard error

(The %stdout and %stderr parts may be missing if the script did not output anything on standard output or standard error).

ScriptLog Directive

Description: | Location of the CGI script error logfile
Syntax: | ScriptLog file-path
Context: | server config, virtual host
Status: | Base
Module: | mod_cgi, mod_cgid

The ScriptLog 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 ServerRoot.

Example

ScriptLog logs/cgi_log

This log will be opened as the user the child processes run as, i.e. the user specified in the main User 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 NOT change the directory permissions to make it writable by the user the child processes run as.

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.

ScriptLogBuffer Directive

Description: | Maximum amount of PUT or POST requests that will be recorded in the scriptlog
Syntax: | ScriptLogBuffer bytes
Default: | ScriptLogBuffer 1024
Context: | server config, virtual host
Status: | Base
Module: | mod_cgi, mod_cgid

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.

ScriptLogLength Directive

Description: | Size limit of the CGI script logfile
Syntax: | ScriptLogLength bytes
Default: | ScriptLogLength 10385760
Context: | server config, virtual host
Status: | Base
Module: | mod_cgi, mod_cgid

ScriptLogLength 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.


mod_cgid - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_cgid

Description: | Execution of CGI scripts using an external CGI daemon
Status: | Base
Module Identifier: | cgid_module
Source File: | mod_cgid.c
Compatibility: | Unix threaded MPMs only

Summary

Except for the optimizations and the additional ScriptSock directive noted below, mod_cgid behaves similarly to mod_cgi. See the mod_cgi summary for additional details about Apache and CGI.

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.

This module is used by default instead of mod_cgi whenever a multi-threaded MPM is selected during the compilation process. At the user level, this module is identical in configuration and operation to mod_cgi. The only exception is the additional directive ScriptSock which gives the name of the socket to use for communication with the cgi daemon.

See also

  • mod_cgi
  • Running CGI programs under different user IDs

CGIDScriptTimeout Directive

Description: | The length of time to wait for more output from the CGI program
Syntax: | CGIDScriptTimeout time[s|ms]
Default: | value of Timeout directive when unset
Context: | server config, virtual host, directory, .htaccess
Status: | Base
Module: | mod_cgid
Compatibility: | CGIDScriptTimeout defaults to zero in releases 2.4 and earlier

This directive limits the length of time to wait for more output from the CGI program. If the time is exceeded, the request and CGI are terminated.

Example

CGIDScriptTimeout 20

ScriptSock Directive

Description: | The filename prefix of the socket to use for communication with the cgi daemon
Syntax: | ScriptSock file-path
Default: | ScriptSock cgisock
Context: | server config
Status: | Base
Module: | mod_cgid

This directive sets the filename prefix of the socket to use for communication with the CGI daemon, an extension corresponding to the process ID of the server will be appended. 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.

If file-path is not an absolute path, the location specified will be relative to the value of DefaultRuntimeDir.

Example

ScriptSock /var/run/cgid.sock

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_charset_lite - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_charset_lite

Description: | Specify character set translation or recoding
Status: | Extension
Module Identifier: | charset_lite_module
Source File: | mod_charset_lite.c

Summary

mod_charset_lite allows the server to change the character set of responses before sending them to the client. In an EBCDIC environment, Apache always translates HTTP protocol content (e.g. response headers) from the code page of the Apache process locale to ISO-8859-1, but not the body of responses. In any environment, mod_charset_lite can be used to specify that response bodies should be translated. For example, if files are stored in EBCDIC, then mod_charset_lite can translate them to ISO-8859-1 before sending them to the client.

This module provides a small subset of configuration mechanisms implemented by Russian Apache and its associated mod_charset.

Common Problems

Invalid character set names

The character set name parameters of CharsetSourceEnc and CharsetDefault must be acceptable to the translation mechanism used by APR on the system where mod_charset_lite 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:

iconv -f charsetsourceenc-value -t charsetdefault-value

Mismatch between character set of content and translation rules

If the translation rules don't make sense for the content, translation can fail in various ways, including:

  • The translation mechanism may return a bad return code, and the connection will be aborted.
  • The translation mechanism may silently place special characters (e.g., question marks) in the output buffer when it cannot translate the input buffer.

CharsetDefault Directive

Description: | Charset to translate into
Syntax: | CharsetDefault charset
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_charset_lite

The CharsetDefault directive specifies the charset that content in the associated container should be translated to.

The value of the charset 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.

Example

<Directory "/export/home/trawick/apacheinst/htdocs/convert">
    CharsetSourceEnc  UTF-16BE
    CharsetDefault    ISO-8859-1
</Directory>
Specifying the same charset for both CharsetSourceEnc and CharsetDefault disables translation. The charset need not match the charset of the response, but it must be a valid charset on the system.

CharsetOptions Directive

Description: | Configures charset translation behavior
Syntax: | CharsetOptions option [option] ...
Default: | CharsetOptions ImplicitAdd
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_charset_lite

The CharsetOptions directive configures certain behaviors of mod_charset_lite. Option can be one of

ImplicitAdd | NoImplicitAdd
The ImplicitAdd keyword specifies that mod_charset_lite 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, NoImplicitAdd should be specified so that mod_charset_lite doesn't add its filter.
TranslateAllMimeTypes | NoTranslateAllMimeTypes
Normally, mod_charset_lite will only perform translation on a small subset of possible mimetypes. When the TranslateAllMimeTypes keyword is specified for a given configuration section, translation is performed without regard for mimetype.

CharsetSourceEnc Directive

Description: | Source charset of files
Syntax: | CharsetSourceEnc charset
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_charset_lite

The CharsetSourceEnc directive specifies the source charset of files in the associated container.

The value of the charset 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.

Example

<Directory "/export/home/trawick/apacheinst/htdocs/convert">
    CharsetSourceEnc  UTF-16BE
    CharsetDefault    ISO-8859-1
</Directory>

The character set names in this example work with the iconv translation support in Solaris 8.

Specifying the same charset for both CharsetSourceEnc and CharsetDefault disables translation. The charset need not match the charset of the response, but it must be a valid charset on the system.


mod_data - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_data

Description: | Convert response body into an RFC2397 data URL
Status: | Extension
Module Identifier: | data_module
Source File: | mod_data.c
Compatibility: | Available in Apache 2.3 and later

Summary

This module provides the ability to convert a response into an RFC2397 data URL.

Data URLs can be embedded inline within web pages using something like the mod_include module, to remove the need for clients to make separate connections to fetch what may potentially be many small images. Data URLs may also be included into pages generated by scripting languages such as PHP.

An example of a data URL

data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAw
AAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFz
ByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSp
a/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJl
ZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uis
F81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PH
hhx4dbgYKAAA7

The filter takes no parameters, and can be added to the filter stack using the SetOutputFilter directive, or any of the directives supported by the mod_filter module.

Configuring the filter

<Location "/data/images">
    SetOutputFilter DATA
</Location>

See also

  • Filters


mod_dav - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dav

Description: | Distributed Authoring and Versioning (WebDAV) functionality
Status: | Extension
Module Identifier: | dav_module
Source File: | mod_dav.c

Summary

This module provides class 1 and class 2 WebDAV ('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.

See also

  • DavLockDB
  • LimitXMLRequestBody
  • WebDAV Resources

Enabling WebDAV

To enable mod_dav, add the following to a container in your httpd.conf file:

Dav On

This enables the DAV file system provider, which is implemented by the mod_dav_fs module. Therefore, that module must be compiled into the server or loaded at runtime using the LoadModule directive.

In addition, a location for the DAV lock database must be specified in the global section of your httpd.conf file using the DavLockDB directive:

DavLockDB /usr/local/apache2/var/DavLock

The directory containing the lock database file must be writable by the User and Group under which Apache is running.

You may wish to add a <Limit> clause inside the <Location> directive to limit access to DAV-enabled locations. If you want to set the maximum amount of bytes that a DAV client can send at one request, you have to use the LimitXMLRequestBody directive. The "normal" LimitRequestBody directive has no effect on DAV requests.

Full Example

DavLockDB "/usr/local/apache2/var/DavLock"

<Directory "/usr/local/apache2/htdocs/foo">
    Require all granted
    Dav On

    AuthType Basic
    AuthName DAV
    AuthUserFile "user.passwd"

    <LimitExcept GET POST OPTIONS>
        Require user admin
    </LimitExcept>
</Directory>

Security Issues

Since DAV access methods allow remote clients to manipulate files on the server, you must take particular care to assure that your server is secure before enabling mod_dav.

Any location on the server where DAV is enabled should be protected by authentication. The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.

In order for mod_dav to manage files, it must be able to write to the directories and files under its control using the User and Group under which Apache is running. New files created will also be owned by this User and Group. For this reason, it is important to control access to this account. The DAV repository is considered private to Apache; modifying files outside of Apache (for example using FTP or filesystem-level tools) should not be allowed.

mod_dav may be subject to various kinds of denial-of-service attacks. The LimitXMLRequestBody directive can be used to limit the amount of memory consumed in parsing large DAV requests. The DavDepthInfinity directive can be used to prevent PROPFIND requests on a very large repository from consuming large amounts of memory. Another possible denial-of-service attack involves a client simply filling up all available disk space with many large files. There is no direct way to prevent this in Apache, so you should avoid giving DAV access to untrusted users.

Complex Configurations

One common request is to use mod_dav to manipulate dynamic files (PHP scripts, CGI scripts, etc). This is difficult because a GET request will always run the script, rather than downloading its contents. One way to avoid this is to map two different URLs to the content, one of which will run the script, and one of which will allow it to be downloaded and manipulated with DAV.

Alias "/phparea" "/home/gstein/php_files"
Alias "/php-source" "/home/gstein/php_files"
<Location "/php-source">
    Dav On
    ForceType text/plain
</Location>

With this setup, http://example.com/phparea can be used to access the output of the PHP scripts, and http://example.com/php-source can be used with a DAV client to manipulate them.

Dav Directive

Description: | Enable WebDAV HTTP methods
Syntax: | Dav On|Off|provider-name
Default: | Dav Off
Context: | directory
Status: | Extension
Module: | mod_dav

Use the Dav directive to enable the WebDAV HTTP methods for the given container:

<Location "/foo">
    Dav On
</Location>

The value On is actually an alias for the default provider filesystem which is served by the mod_dav_fs module. Note, that once you have DAV enabled for some location, it cannot be disabled for sublocations. For a complete configuration example have a look at the section above.

Do not enable WebDAV until you have secured your server. Otherwise everyone will be able to distribute files on your system.

DavDepthInfinity Directive

Description: | Allow PROPFIND, Depth: Infinity requests
Syntax: | DavDepthInfinity on|off
Default: | DavDepthInfinity off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_dav

Use the DavDepthInfinity 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.

DavMinTimeout Directive

Description: | Minimum amount of time the server holds a lock on a DAV resource
Syntax: | DavMinTimeout seconds
Default: | DavMinTimeout 0
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_dav

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.

Use the DavMinTimeout 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 DavMinTimeout can override this to a higher value (like 600 seconds) to reduce the chance of the client losing the lock due to network latency.

Example

<Location "/MSWord">
    DavMinTimeout 600
</Location>

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_dav_fs - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dav_fs

Description: | Filesystem provider for mod_dav
Status: | Extension
Module Identifier: | dav_fs_module
Source File: | mod_dav_fs.c

Summary

This module requires the service of mod_dav. It acts as a support module for mod_dav and provides access to resources located in the server's file system. The formal name of this provider is filesystem. mod_dav backend providers will be invoked by using the Dav directive:

Example

Dav filesystem

Since filesystem is the default provider for mod_dav, you may simply use the value On instead.

See also

  • mod_dav

DavLockDB Directive

Description: | Location of the DAV lock database
Syntax: | DavLockDB file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_dav_fs

Use the DavLockDB directive to specify the full path to the lock database, excluding an extension. If the path is not absolute, it will be taken relative to ServerRoot. The implementation of mod_dav_fs uses a SDBM database to track user locks.

Example

DavLockDB "var/DavLock"

The directory containing the lock database file must be writable by the User and Group under which Apache is running. For security reasons, you should create a directory for this purpose rather than changing the permissions on an existing directory. In the above example, Apache will create files in the var/ directory under the ServerRoot with the base filename DavLock and extension name chosen by the server.


mod_dav_lock - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dav_lock

Description: | Generic locking module for mod_dav
Status: | Extension
Module Identifier: | dav_lock_module
Source File: | mod_dav_lock.c
Compatibility: | Available in version 2.1 and later

Summary

This module implements a generic locking API which can be used by any backend provider of mod_dav. It requires at least the service of mod_dav. But without a backend provider which makes use of it, it's useless and should not be loaded into the server. A sample backend module which actually utilizes mod_dav_lock is mod_dav_svn, the subversion provider module.

Note that mod_dav_fs does not need this generic locking module, because it uses its own more specialized version.

In order to make mod_dav_lock functional, you just have to specify the location of the lock database using the DavGenericLockDB directive described below.

Developer's Note

In order to retrieve the pointer to the locking provider function, you have to use the ap_lookup_provider API with the arguments dav-lock, generic, and 0.

See also

  • mod_dav

DavGenericLockDB Directive

Description: | Location of the DAV lock database
Syntax: | DavGenericLockDB file-path
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_dav_lock

Use the DavGenericLockDB directive to specify the full path to the lock database, excluding an extension. If the path is not absolute, it will be interpreted relative to ServerRoot. The implementation of mod_dav_lock uses a SDBM database to track user locks.

Example

DavGenericLockDB var/DavLock

The directory containing the lock database file must be writable by the User and Group under which Apache is running. For security reasons, you should create a directory for this purpose rather than changing the permissions on an existing directory. In the above example, Apache will create files in the var/ directory under the ServerRoot with the base filename DavLock and an extension added by the server.


mod_dbd - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dbd

Description: | Manages SQL database connections
Status: | Extension
Module Identifier: | dbd_module
Source File: | mod_dbd.c
Compatibility: | Version 2.1 and later

Summary

mod_dbd manages SQL database connections using APR. It provides database connections on request to modules requiring SQL database functions, and takes care of managing databases with optimal efficiency and scalability for both threaded and non-threaded MPMs. For details, see the APR website and this overview of the Apache DBD Framework by its original developer.

See also

  • Password Formats

Connection Pooling

This module manages database connections, in a manner optimised for the platform. On non-threaded platforms, it provides a persistent connection in the manner of classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). On threaded platform, it provides an altogether more scalable and efficient connection pool, as described in this article at ApacheTutor. Note that mod_dbd supersedes the modules presented in that article.

Apache DBD API

mod_dbd exports five functions for other modules to use. The API is as follows:

typedef struct {
    apr_dbd_t *handle;
    apr_dbd_driver_t *driver;
    apr_hash_t *prepared;
} ap_dbd_t;

/* Export functions to access the database */

/* acquire a connection that MUST be explicitly closed.
 * Returns NULL on error
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);

/* release a connection acquired with ap_dbd_open */
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);

/* acquire a connection that will have the lifetime of a request
 * and MUST NOT be explicitly closed.  Return NULL on error.
 * This is the preferred function for most applications.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);

/* acquire a connection that will have the lifetime of a connection
 * and MUST NOT be explicitly closed.  Return NULL on error.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);

/* Prepare a statement for use by a client module */
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);

/* Also export them as optional functions for modules that prefer it */
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));

SQL Prepared Statements

mod_dbd supports SQL prepared statements on behalf of modules that may wish to use them. Each prepared statement must be assigned a name (label), and they are stored in a hash: the prepared field of an ap_dbd_t. Hash entries are of type apr_dbd_prepared_t and can be used in any of the apr_dbd prepared statement SQL query or select commands.

It is up to dbd user modules to use the prepared statements and document what statements can be specified in httpd.conf, or to provide their own directives and use ap_dbd_prepare.

Caveat

When using prepared statements with a MySQL database, it is preferred to set reconnect to 0 in the connection string as to avoid errors that arise from the MySQL client reconnecting without properly resetting the prepared statements. If set to 1, any broken connections will be attempted fixed, but as mod_dbd is not informed, the prepared statements will be invalidated.

SECURITY WARNING

Any web/database application needs to secure itself against SQL injection attacks. In most cases, Apache DBD is safe, because applications use prepared statements, and untrusted inputs are only ever used as data. Of course, if you use it via third-party modules, you should ascertain what precautions they may require.

However, the FreeTDS driver is inherently unsafe. The underlying library doesn't support prepared statements, so the driver emulates them, and the untrusted input is merged into the SQL statement.

It can be made safe by untainting all inputs: a process inspired by Perl's taint checking. Each input is matched against a regexp, and only the match is used, according to the Perl idiom:

  $untrusted =~ /([a-z]+)/;
  $trusted = $1;

To use this, the untainting regexps must be included in the prepared statements configured. The regexp follows immediately after the % in the prepared statement, and is enclosed in curly brackets {}. For example, if your application expects alphanumeric input, you can use:

"SELECT foo FROM bar WHERE input = %s"

with other drivers, and suffer nothing worse than a failed query. But with FreeTDS you'd need:

"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"

Now anything that doesn't match the regexp's $1 match is discarded, so the statement is safe.

An alternative to this may be the third-party ODBC driver, which offers the security of genuine prepared statements.

DBDExptime Directive

Description: | Keepalive time for idle connections
Syntax: | DBDExptime time-in-seconds
Default: | DBDExptime 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the time to keep idle connections alive when the number of connections specified in DBDKeep has been exceeded (threaded platforms only).

DBDInitSQL Directive

Description: | Execute an SQL statement after connecting to a database
Syntax: | DBDInitSQL "SQL statement"
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Modules, that wish it, can have one or more SQL statements executed when a connection to a database is created. Example usage could be initializing certain values or adding a log entry when a new connection is made to the database.

DBDKeep Directive

Description: | Maximum sustained number of connections
Syntax: | DBDKeep number
Default: | DBDKeep 2
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the maximum number of connections per process to be sustained, other than for handling peak demand (threaded platforms only).

DBDMax Directive

Description: | Maximum number of connections
Syntax: | DBDMax number
Default: | DBDMax 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the hard maximum number of connections per process (threaded platforms only).

DBDMin Directive

Description: | Minimum number of connections
Syntax: | DBDMin number
Default: | DBDMin 1
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the minimum number of connections per process (threaded platforms only).

DBDParams Directive

Description: | Parameters for database connection
Syntax: | DBDParams param1=value1[,param2=value2]
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

As required by the underlying driver. Typically this will be used to pass whatever cannot be defaulted amongst username, password, database name, hostname and port number for connection.

Connection string parameters for current drivers include:

FreeTDS (for MSSQL and SyBase)
username, password, appname, dbname, host, charset, lang, server
MySQL
host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect
Oracle
user, pass, dbname, server
PostgreSQL
The connection string is passed straight through to PQconnectdb
SQLite2
The connection string is split on a colon, and part1:part2 is used as sqlite_open(part1, atoi(part2), NULL)
SQLite3
The connection string is passed straight through to sqlite3_open
ODBC
datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize

DBDPersist Directive

Description: | Whether to use persistent connections
Syntax: | DBDPersist On|Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

If set to Off, persistent and pooled connections are disabled. A new database connection is opened when requested by a client, and closed immediately on release. This option is for debugging and low-usage servers.

The default is to enable a pool of persistent connections (or a single LAMP-style persistent connection in the case of a non-threaded server), and should almost always be used in operation.

Prior to version 2.2.2, this directive accepted only the values 0 and 1 instead of Off and On, respectively.

DBDPrepareSQL Directive

Description: | Define an SQL prepared statement
Syntax: | DBDPrepareSQL "SQL statement" label
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

For modules such as authentication that repeatedly use a single SQL statement, optimum performance is achieved by preparing the statement at startup rather than every time it is used. This directive prepares an SQL statement and assigns it a label.

DBDriver Directive

Description: | Specify an SQL driver
Syntax: | DBDriver name
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Selects an apr_dbd driver by name. The driver must be installed on your system (on most systems, it will be a shared object or dll). For example, DBDriver mysql will select the MySQL driver in apr_dbd_mysql.so.


mod_deflate - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_deflate

Description: | Compress content before it is delivered to the client
Status: | Extension
Module Identifier: | deflate_module
Source File: | mod_deflate.c

Summary

The mod_deflate module provides the DEFLATE output filter that allows output from your server to be compressed before being sent to the client over the network.

See also

  • Filters

Supported Encodings

The gzip encoding is the only one supported to ensure complete compatibility with old browser implementations. The deflate encoding is not supported, please check the zlib's documentation for a complete explanation.

Sample Configurations

Compression and TLS

Some web applications are vulnerable to an information disclosure attack when a TLS connection carries deflate compressed data. For more information, review the details of the "BREACH" family of attacks.

This is a simple configuration that compresses common text-based content types.

Compress only a few types

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript

Enabling Compression

Compression and TLS

Some web applications are vulnerable to an information disclosure attack when a TLS connection carries deflate compressed data. For more information, review the details of the "BREACH" family of attacks.

Output Compression

Compression is implemented by the DEFLATE filter. The following directive will enable compression for documents in the container where it is placed:

SetOutputFilter DEFLATE
SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)$" no-gzip

If you want to restrict the compression to particular MIME types in general, you may use the AddOutputFilterByType directive. Here is an example of enabling compression only for the html files of the Apache documentation:

<Directory "/your-server-root/manual">
    AddOutputFilterByType DEFLATE text/html
</Directory>

Note

The DEFLATE filter is always inserted after RESOURCE filters like PHP or SSI. It never touches internal subrequests.

Note

There is an environment variable force-gzip, set via SetEnv, which will ignore the accept-encoding setting of your browser and will send compressed output.

Output Decompression

The mod_deflate module also provides a filter for inflating/uncompressing a gzip compressed response body. In order to activate this feature you have to insert the INFLATE filter into the output filter chain using SetOutputFilter or AddOutputFilter, for example:

<Location "/dav-area">
    ProxyPass "http://example.com/"
    SetOutputFilter INFLATE
</Location>

This Example will uncompress gzip'ed output from example.com, so other filters can do further processing with it.

Input Decompression

The mod_deflate module also provides a filter for decompressing a gzip compressed request body . In order to activate this feature you have to insert the DEFLATE filter into the input filter chain using SetInputFilter or AddInputFilter, for example:

<Location "/dav-area">
    SetInputFilter DEFLATE
</Location>

Now if a request contains a Content-Encoding: gzip header, the body will be automatically decompressed. Few browsers have the ability to gzip request bodies. However, some special applications actually do support request compression, for instance some WebDAV clients.

Note on Content-Length

If you evaluate the request body yourself, don't trust the Content-Length header! The Content-Length header reflects the length of the incoming data from the client and not the byte count of the decompressed data stream.

Dealing with proxy servers

The mod_deflate module sends a Vary: Accept-Encoding HTTP response header to alert proxies that a cached response should be sent only to clients that send the appropriate Accept-Encoding request header. This prevents compressed content from being sent to a client that will not understand it.

If you use some special exclusions dependent on, for example, the User-Agent header, you must manually configure an addition to the Vary header to alert proxies of the additional restrictions. For example, in a typical configuration where the addition of the DEFLATE filter depends on the User-Agent, you should add:

Header append Vary User-Agent

If your decision about compression depends on other information than request headers (e.g. HTTP version), you have to set the Vary header to the value *. This prevents compliant proxies from caching entirely.

Example

Header set Vary *

Serving pre-compressed content

Since mod_deflate re-compresses content each time a request is made, some performance benefit can be derived by pre-compressing the content and telling mod_deflate to serve them without re-compressing them. This may be accomplished using a configuration like the following:

<IfModule mod_headers.c>
    # Serve gzip compressed CSS files if they exist
    # and the client accepts gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" -s
    RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]

    # Serve gzip compressed JS files if they exist
    # and the client accepts gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" -s
    RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]

    # Serve correct content types, and prevent mod_deflate double gzip.
    RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
    RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]

    <FilesMatch "(\.js\.gz|\.css\.gz)$">
      # Serve correct encoding type.
      Header append Content-Encoding gzip

      # Force proxies to cache gzipped &
      # non-gzipped css/js files separately.
      Header append Vary Accept-Encoding
    </FilesMatch>
</IfModule>

DeflateBufferSize Directive

Description: | Fragment size to be compressed at one time by zlib
Syntax: | DeflateBufferSize value
Default: | DeflateBufferSize 8096
Context: | server config, virtual host
Status: | Extension
Module: | mod_deflate

The DeflateBufferSize directive specifies the size in bytes of the fragments that zlib should compress at one time. If the compressed response size is bigger than the one specified by this directive then httpd will switch to chunked encoding (HTTP header Transfer-Encoding set to Chunked), with the side effect of not setting any Content-Length HTTP header. This is particularly important when httpd works behind reverse caching proxies or when httpd is configured with mod_cache and mod_cache_disk because HTTP responses without any Content-Length header might not be cached.

DeflateCompressionLevel Directive

Description: | How much compression do we apply to the output
Syntax: | DeflateCompressionLevel value
Default: | Zlib's default
Context: | server config, virtual host
Status: | Extension
Module: | mod_deflate

The DeflateCompressionLevel directive specifies what level of compression should be used, the higher the value, the better the compression, but the more CPU time is required to achieve this.

The value must between 1 (less compression) and 9 (more compression).

DeflateFilterNote Directive

Description: | Places the compression ratio in a note for logging
Syntax: | DeflateFilterNote [type] notename
Context: | server config, virtual host
Status: | Extension
Module: | mod_deflate

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. You can use that note for statistical purposes by adding the value to your access log.

Example

      DeflateFilterNote ratio

      LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
      CustomLog "logs/deflate_log" deflate

If you want to extract more accurate values from your logs, you can use the type argument to specify the type of data left as a note for logging. type can be one of:

Input
Store the byte count of the filter's input stream in the note.
Output
Store the byte count of the filter's output stream in the note.
Ratio
Store the compression ratio (output/input * 100) in the note. This is the default, if the type argument is omitted.

Thus you may log it this way:

Accurate Logging

DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio

LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog "logs/deflate_log" deflate

See also

  • mod_log_config

DeflateInflateLimitRequestBody Directive

Description: | Maximum size of inflated request bodies
Syntax: | DeflateInflateLimitRequestBodyvalue
Default: | None, but LimitRequestBody applies after deflation
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_deflate
Compatibility: | 2.4.10 and later

The DeflateInflateLimitRequestBody directive specifies the maximum size of an inflated request body. If it is unset, LimitRequestBody is applied to the inflated body.

DeflateInflateRatioBurst Directive

Description: | Maximum number of times the inflation ratio for request bodies can be crossed
Syntax: | DeflateInflateRatioBurst value
Default: | 3
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_deflate
Compatibility: | 2.4.10 and later

The DeflateInflateRatioBurst directive specifies the maximum number of times the DeflateInflateRatioLimit can be crossed before terminating the request.

DeflateInflateRatioLimit Directive

Description: | Maximum inflation ratio for request bodies
Syntax: | DeflateInflateRatioLimit value
Default: | 200
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_deflate
Compatibility: | 2.4.10 and later

The DeflateInflateRatioLimit directive specifies the maximum ratio of deflated to inflated size of an inflated request body. This ratio is checked as the body is streamed in, and if crossed more than DeflateInflateRatioBurst times, the request will be terminated.

DeflateMemLevel Directive

Description: | How much memory should be used by zlib for compression
Syntax: | DeflateMemLevel value
Default: | DeflateMemLevel 9
Context: | server config, virtual host
Status: | Extension
Module: | mod_deflate

The DeflateMemLevel directive specifies how much memory should be used by zlib for compression (a value between 1 and 9).

DeflateWindowSize Directive

Description: | Zlib compression window size
Syntax: | DeflateWindowSize value
Default: | DeflateWindowSize 15
Context: | server config, virtual host
Status: | Extension
Module: | mod_deflate

The DeflateWindowSize directive specifies the zlib compression window size (a value between 1 and 15). Generally, the higher the window size, the higher can the compression ratio be expected.


mod_dialup - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dialup

Description: | Send static content at a bandwidth rate limit, defined by the various old modem standards
Status: | Experimental
Module Identifier: | dialup_module
Source File: | mod_dialup.c

Summary

It is a module that sends static content at a bandwidth rate limit, defined by the various old modem standards. So, you can browse your site with a 56k V.92 modem, by adding something like this:

<Location "/mysite">
    ModemStandard "V.92"
</Location>

Previously to do bandwidth rate limiting modules would have to block an entire thread, for each client, and insert sleeps to slow the bandwidth down. Using the new suspend feature, a handler can get callback N milliseconds in the future, and it will be invoked by the Event MPM on a different thread, once the timer hits. From there the handler can continue to send data to the client.

ModemStandard Directive

Description: | Modem standard to simulate
Syntax: | ModemStandard V.21|V.26bis|V.32|V.34|V.92
Context: | directory
Status: | Experimental
Module: | mod_dialup

Specify what modem standard you wish to simulate.

<Location "/mysite">
    ModemStandard "V.26bis"
</Location>

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_dir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_dir

Açıklama: | Bölü çizgisiyle biten yönlendirmeleri yapar ve dizin içeriği dosyalarını sunar.
Durum: | Temel
Modül Betimleyici: | dir_module
Kaynak Dosyası: | mod_dir.c

Özet

Bir dizin içerik dosyası şu iki kaynaktan birinden gelebilir:

  • Kullanıcı tarafından yazılmış ve ismi genellikle index.html olan bir dosya. Dosya ismi DirectoryIndex yönergesi ile belirlenir. Bu, mod_dir modülü tarafından denetlenir.
  • Aksi takdirde içerik listesi sunucu tarafından üretilir. Bu, mod_autoindex modülü tarafından sağlanır.

Bu iki işlev tamamen birbirinden ayrıdır, dolayısıyla eğer isterseniz kendiliğinden dizin içerik listesi üretimini tamamen iptal edebilirsiniz.

Sunucu http://example.com/filanca/birdizin şeklinde bir istek aldığında birdizin bir dizinin ismiyse ‘bölü çizgisiyle biten’ bir yönlendirme söz konusudur. Dizinler URL sonuna bir bölü çizgisi eklenmesini gerektirir, bu bakımdan mod_dir modülü isteği http://example.com/filanca/birdizin/ şeklinde yönlendirir.

DirectoryCheckHandler Yönergesi

Açıklama: | Başka bir eylemci yapılandırılmışsa bu modülün nasıl yanıt vereceğini belirler
Sözdizimi: | DirectoryCheckHandler On|Off
Öntanımlı: | DirectoryCheckHandler Off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_dir
Uyumluluk: | 2.4.8 ve sonrasında kullanılabilmektedir. 2.4 öncesi sürümler örtük olarak "DirectoryCheckHandler ON" belirtilmiş gibi davranır.

DirectoryCheckHandler yönergesi, geçerli URL için başka bir eylemcinin yapılandırılmış olması durumunda, mod_dir modülünün index dosyaları için dizine mi bakacağını yoksa URL'nin sonuna bölü çizgisi mi ekleyeceğini belirler. Eylemciler SetHandler gibi yönergelerle atanabileceği gibi dizin işlemleri sırasında mod_rewrite gibi modüller tarafından da atanabilir.

2.4 öncesi sürümlerde, bir URL için başka bir eylemcinin yapılandılmış olması durumunda bu modül herhangi bir eylemde bulunmaz ve sonuç olarak, tüm dizin için bir SetHandler belirtildiği durumda index dosyalarının sunulmasının yanında mod_rewrite gibi modüller de ayrıca bazı çelişkili sonuçlar oluşturabilir.

DirectoryIndex Yönergesi

Açıklama: | İstemci bir dizin istediğinde dizin içeriğini listeler.
Sözdizimi: | DirectoryIndex disabled | yerel-url [yerel-url] ...
Öntanımlı: | DirectoryIndex index.html
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_dir

DirectoryIndex yönergesi, istemci, dizinin sonuna bir bölü çizgisi ekleyerek dizin içeriğinin listelenmesini istediğinde bakılmak üzere özkaynakları listeler. yerel-url, sunucu üstünde istenen dizine göreli bir belgenin URL’sidir; normal olarak dizin içindeki bir dosyanın ismidir. Çeşitli URL’ler verilebilirse de sunucu daima ilk bulduğuyla dönecektir. Eğer özkaynakların hiçbiri yoksa ve Indexes seçeneği atanmışsa sunucu dizin içeriğinden bir liste üretecektir.

DirectoryIndex index.html

Bu yapılandırmadan sonra yapılan bir http://sunucum/belgeler/ isteğine karşılık, sunucu, mevcutsa http://sunucum/belgeler/index.html dosyasını döndürecek, değilse ürettiği dizin içerik listesini gönderecektir.

Belgelerin dizine göreli olmasının gerekmediğine dikkat ediniz.

DirectoryIndex index.html index.txt  /cgi-bin/index.pl

Bu örnekte ise dizin içinde ne index.html ne de index.txt mevcut olduğunda /cgi-bin/index.pl CGI betiği çalıştırılacaktır.

disabled değeri tek başına mod_dir’in bir dizin listesi aramasını engeller. disabled değiştirgesi öncesinde ve sonrasında başka bir değiştirge hatta bir disabled daha olsa bile sadece bir disabled verilmiş gibi yorumlanır.

Bilginize: Aynı bağlamdaki çok sayıda DirectoryIndex yönergesi bir öncekini değiştirmek yerine onun bulunduğu listeye eklenir:

# 1. örnek: İçerik dosyası olarak index.html atayıp sonraki satırda buna
# index.php'yi ekleyebilirsiniz.
<Directory "/foo">
    DirectoryIndex index.html
    DirectoryIndex index.php
</Directory>

# 2. Örnek: Atamaların tet bir satırda yapıldığı bu örnek 1. örneğe denktir.
<Directory "/foo">
    DirectoryIndex index.html index.php
</Directory>

# 3. Örnek: Listeyi tamamen değiştirmek için, listeyi önce sıfırlamalısınız:
# Bu örnekte içerik dosyası olarak listede sadece index.php kalır.
<Directory "/foo">
    DirectoryIndex index.html
    DirectoryIndex disabled
    DirectoryIndex index.php
</Directory>

DirectoryIndexRedirect Yönergesi

Açıklama: | Dizin içerik listeleri için harici bir yönlendirme yapılandırır.
Sözdizimi: | DirectoryIndexRedirect on | off | permanent | temp | seeother | 3xx-kodu
Öntanımlı: | DirectoryIndexRedirect off
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_dir
Uyumluluk: | Apache HTTP Sunucusunun 2.3.14 ve sonraki sürümlerinde kullanılabilmektedir.

Öntanımlı olarak, DirectoryIndex listeyi istemciye şeffaf olarak seçip gönderir. DirectoryIndexRedirect ise harici bir yönlendirmeye sebep olur.

Bunlardan biri kullanılabilir:

  • on: Dizin listesi kaynağına bir 302 yönlendirmesi yapılır.
  • off: Bir yönlendirme yapılmaz. mod_dir için eski davranış böyleydi.
  • permanent: Dizin listesi kaynağına bir 301 (kalıcı) yönlendirmesi yapılır.
  • temp: Bu on ile aynı etkiye sahiptir.
  • seeother: Dizin listesi kaynağına bir 303 yönlendirmesi ("diğerine bak" olarak da bilinir)yapılır.
  • 3xx-code: 3xx kodu ile seçilen yönlendirme yapılır.

Örnek

DirectoryIndexRedirect on

http://example.com/docs/ için yapılan bir istek, http://example.com/docs/index.html (mevcutsa) adresine geçici bir yönlendirme döndürür.

DirectorySlash Yönergesi

Açıklama: | Bölü çizgisi ile biten yönlendirmeleri açar/kapar.
Sözdizimi: | DirectorySlash On|Off
Öntanımlı: | DirectorySlash On
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_dir

DirectorySlash yönergesi, bir dizin isteğinde bulunan URL’lerin sonuna mod_dir modülü tarafından bir bölü çizgisi eklenip eklenmeyeceğini belirler.

Normalde, bir kullanıcı sona bir bölü çizgisi eklemeden bir dizin için istekte bulunursa mod_dir zaten onu aynı özkaynağa yönlendirir, fakat isteğin sonuna bir bölü çizgisi eklenmesinin bazı iyi sebepleri vardır:

  • Kullanıcı bunun sonucunda meşru bir URL ile istekte bulunmuş olur.
  • mod_autoindex gerektiği gibi çalışır. Yoksa bağlantıdaki yolu sunamayacağından yanlış yolu gösterirdi.
  • DirectoryIndex yönergesi sadece bölü çizgisi ile biten dizin istekleri için değerlendirilir.
  • HTML sayfa içindeki göreli URL başvuruları gerektiği gibi çalışacaktır.

Siz yine de bu etkiyi istemezseniz ve yukarıdaki sebepler de size uygun değilse yönlendirmeyi aşağıdaki gibi kapatabilirsiniz. Ancak bunu yaparken dikkatli olun, bununla ilgili bazı güvenlik sorunları olasılığı vardır.

# Aşağıdaki güvenlik uyarısına bakınız!

<Location "/bir/yol">

  DirectorySlash Off

  SetHandler bir-eylemci

</Location>

Güvenlik Uyarı

Bölü çizgisi ile biten yönlendirmelerin kapatılması bir bilginin istemeyek açığa çıkmasına sebep olabilir. mod_autoindex modülünün etkin olduğunu (Options +Indexes) ve DirectoryIndex ile geçerli bir özkaynağın (index.html olsun) atandığını ama bu URL için başka hiçbir özel eylemci tanımlanmadığını varsayalım. Bu durumda bölü çizgisi ile biten bir istek olduğunda index.html dosyası sunulurdu. Fakat bölü çizgisi ile bitmeyen bir istek dizin içeriğinin listelenmesi ile sonuçlanırdı.

Bir yönlendirme sözkonusu olduğunda bazı tarayıcıların yanlışlıkla POST isteklerini GET istekleri haline getirme (böylece POST verisi iptal olur) olasılığı olduğuna da dikkat edin.

FallbackResource Yönergesi

Açıklama: | Bir dosya ile eşleşmeyen istekler için öntanımlı URL tanımlar
Sözdizimi: | FallbackResource disabled | yerel-url
Öntanımlı: | disabled - httpd 404 döndürecektir (Yok)
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | Indexes
Durum: | Temel
Modül: | mod_dir
Uyumluluk: | disabled değiştirgesi 2.4.4 sürümü ve sonrasında kullanılabilmektedir.

Dosya sisteminde bulunmayan bir dosya için istek yapıldığında HTTP'nin 404 (Yok) hatasını döndürmemesi için sunulacak dosyanın yolunu tanımlar. Örnek:

FallbackResource /not-404.php

Bu satırla, (mevcut dosyaları etkilemeden) mevcut olmayan dosyaların yerine not-404.php dosyası sunulacaktır.

Belli bir dizindeki mevcut bir dosya veya betik için yapılanlar dışındaki tüm isteklerin tek bir dosya veya özkaynakla yerine getirilmesi sıkça istenen bir durum olup bu mekanizmaya 'ön denetleyici' adı verilir.

httpd'nin önceki sürümlerinde bir dosya veya dizinin varlığının sınanması için genellikle mod_rewrite modülü ve -f ve -d kullanımı gerekirdi. Bunun için şimdi tek satırlık bir yapılandırma yeterli olmaktadır.

FallbackResource /index.php

Resim, CSS dosyaları gibi mevcut dosyalar normal olarak sunulur.

Üst dizinden hiçbir şeyin miras alınmaması isteniyorsa bu özelliği kapatmak için disabled değiştirgesini kullanın.

http://example.com/blog/ gibi bir alt URI yerel-url olarak sağlanır:

<Directory "/web/example.com/htdocs/blog">
  FallbackResource /blog/index.php
</Directory>

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_dumpio - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_dumpio

Description: | Dumps all I/O to error log as desired.
Status: | Extension
Module Identifier: | dumpio_module
Source File: | mod_dumpio.c

Summary

mod_dumpio allows for the logging of all input received by Apache and/or all output sent by Apache to be logged (dumped) to the error.log file.

The data logging is done right after SSL decoding (for input) and right before SSL encoding (for output). As can be expected, this can produce extreme volumes of data, and should only be used when debugging problems.

Enabling dumpio Support

To enable the module, it should be compiled and loaded in to your running Apache configuration. Logging can then be enabled or disabled separately for input and output via the below directives. Additionally, mod_dumpio needs to be configured to LogLevel trace7:

LogLevel dumpio:trace7

DumpIOInput Directive

Description: | Dump all input data to the error log
Syntax: | DumpIOInput On|Off
Default: | DumpIOInput Off
Context: | server config
Status: | Extension
Module: | mod_dumpio
Compatibility: | DumpIOInput is only available in Apache 2.1.3 and later.

Enable dumping of all input.

Example

DumpIOInput On

DumpIOOutput Directive

Description: | Dump all output data to the error log
Syntax: | DumpIOOutput On|Off
Default: | DumpIOOutput Off
Context: | server config
Status: | Extension
Module: | mod_dumpio
Compatibility: | DumpIOOutput is only available in Apache 2.1.3 and later.

Enable dumping of all output.

Example

DumpIOOutput On

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_echo - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_echo

Description: | A simple echo server to illustrate protocol modules
Status: | Experimental
Module Identifier: | echo_module
Source File: | mod_echo.c

Summary

This module provides an example protocol module to illustrate the concept. It provides a simple echo server. Telnet to it and type stuff, and it will echo it.

ProtocolEcho Directive

Description: | Turn the echo server on or off
Syntax: | ProtocolEcho On|Off
Default: | ProtocolEcho Off
Context: | server config, virtual host
Status: | Experimental
Module: | mod_echo

The ProtocolEcho directive enables or disables the echo server.

Example

ProtocolEcho On

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_env - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_env

Açıklama: | CGI betiklerine ve SSI sayfalarına aktarılan değişkenlere müdahale etmek için kullanılır.
Durum: | Temel
Modül Betimleyici: | env_module
Kaynak Dosyası: | mod_env.c

Özet

Bu modül Apache HTTP Sunucusunun çeşitli modülleri tarafınan kullanılan dahili ortam değişkenlerime müdahale etmeyi mümkün kılar. bu değişkenler ayrıca, CGI betiklerine yerel ortam değişkenleri olarak sunulur ve SSI sayfalarında da kullanılabilir. Ortam değişkenleri httpd süreci başlatılırken kabuktan aktarılabilir. Bundan başka, yapılandırma sürecinde tanımlı veya tanımsız yapılabilirler.

Ayrıca bakınız:

  • Ortam Değişkenleri
  • SetEnvIf

PassEnv Yönergesi

Açıklama: | Ortam değişkenlerini kabuktan aktarır.
Sözdizimi: | PassEnv ortam-değişkeni [ortam-değişkeni] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_env

Dahili ortam değişkenleri olarak kullanılmak üzere sistem ortam değişkenlerini içeri aktarmak için kullanılır. Bunlar daha sonra Apache HTTP Sunucusunun modüllerinden kullanılabilir, CGI betiklerine ve SSI sayfalarında aktarılabilir. Değerler httpd süreci başlatılırken kabuğun işletim sistemi ortamından gelir.

Örnek

PassEnv LD_LIBRARY_PATH

SetEnv Yönergesi

Açıklama: | Ortam değişkenlerini tanımlar.
Sözdizimi: | SetEnv ortam-değişkeni [değer]
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_env

CGI betiklerine ve SSI sayfalarına aktarılmak ve Apache HTTP Sunucusu modüllerinde kullanılmak üzere bir dahili ortam değişkeni tanımlanmasını sağlar.

SetEnv SPECIAL_PATH /foo/bin

Bir değer belirtilmezse değişkene boş dizgi atanır.

Bu yönerge tarafından atanan dahili ortam değişkenleri, en başta işleme sokulan, ereşem denetimi, URI-dosya ismi eşleştirmesi gibi istek işleme yönergelerinden sonra işleme sokulur. Eğer atadığınız ortam değişkeni, bir RewriteRule yönergesindeki gibi erken işlem aşamalarına girdi sağlıyorsa, bu durumda ortam değişkenini SetEnvIf ile atamalısınız.

Ayrıca bakınız:

  • Environment Variables

UnsetEnv Yönergesi

Açıklama: | Ortamdaki değişkenleri tanımsız hale getirir.
Sözdizimi: | UnsetEnv ortam-değişkeni [ortam-değişkeni] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_env

CGI betiklerine ve SSI sayfalarına bir daha aktarılmamak üzere bir dahili ortam değişkenini siler.

UnsetEnv LD_LIBRARY_PATH

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_example_hooks - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_example_hooks

Description: | Illustrates the Apache module API
Status: | Experimental
Module Identifier: | example_hooks_module
Source File: | mod_example_hooks.c

Summary

The files in the modules/examples directory under the Apache distribution directory tree are provided as an example to those that wish to write modules that use the Apache API.

The main file is mod_example_hooks.c, 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!

The example module is an actual working module. If you link it into your server, enable the "example-hooks-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.

Compiling the example_hooks module

To include the example_hooks module in your server, follow the steps below:

  1. Run configure with --enable-example-hooks option.
  2. Make the server (run "make").

To add another module of your own:

  1. cp modules/examples/mod_example_hooks.c modules/new_module/mod_myexample.c
  2. Modify the file.
  3. Create modules/new_module/config.m4.
    1. Add APACHE_MODPATH_INIT(new_module).
    2. Copy APACHE_MODULE line with "example_hooks" from modules/examples/config.m4.
    3. Replace the first argument "example_hooks" with myexample.
    4. Replace the second argument with brief description of your module. It will be used in configure --help.
    5. If your module needs additional C compiler flags, linker flags or libraries, add them to CFLAGS, LDFLAGS and LIBS accordingly. See other config.m4 files in modules directory for examples.
    6. Add APACHE_MODPATH_FINISH.
  4. Create module/new_module/Makefile.in. If your module doesn't need special build instructions, all you need to have in that file is include $(top_srcdir)/build/special.mk.
  5. Run ./buildconf from the top-level directory.
  6. Build the server with --enable-myexample

Using the mod_example_hooks Module

To activate the example_hooks module, include a block similar to the following in your httpd.conf file:

<Location "/example-hooks-info">
   SetHandler example-hooks-handler
</Location>

As an alternative, you can put the following into a .htaccess file and then request the file "test.example" from that location:

AddHandler example-hooks-handler ".example"

After reloading/restarting your server, you should be able to browse to this location and see the brief display mentioned earlier.

Example Directive

Description: | Demonstration directive to illustrate the Apache module API
Syntax: | Example
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_example_hooks

The Example 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-hooks 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 "Example directive declared here: YES/NO".


mod_expires - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_expires

Description: | Generation of Expires and Cache-Control HTTP headers according to user-specified criteria
Status: | Extension
Module Identifier: | expires_module
Source File: | mod_expires.c

Summary

This module controls the setting of the Expires HTTP header and the max-age directive of the Cache-Control 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.

These HTTP headers are 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.

To modify Cache-Control directives other than max-age (see RFC 2616 section 14.9), you can use the Header directive.

When the Expires header is already part of the response generated by the server, for example when generated by a CGI script or proxied from an origin server, this module does not change or add an Expires or Cache-Control header.

Alternate Interval Syntax

The ExpiresDefault and ExpiresByType directives can also be defined in a more readable syntax of the form:

ExpiresDefault "base  [plus num type] [num type] ..."
ExpiresByType type/encoding "base  [plus num type] [num type] ..."

where base is one of:

  • access
  • now (equivalent to 'access')
  • modification

The plus keyword is optional. num should be an integer value [acceptable to atoi()], and type is one of:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

For example, any of the following directives can be used to make documents expire 1 month after being accessed, by default:

ExpiresDefault "access plus 1 month"
ExpiresDefault "access plus 4 weeks"
ExpiresDefault "access plus 30 days"

The expiry time can be fine-tuned by adding several 'num type' clauses:

ExpiresByType text/html "access plus 1 month 15 days 2 hours"
ExpiresByType image/gif "modification plus 5 hours 3 minutes"

Note that if you use a modification date based setting, the Expires header will not 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.

ExpiresActive Directive

Description: | Enables generation of Expires headers
Syntax: | ExpiresActive On|Off
Default: | ExpiresActive Off
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

This directive enables or disables the generation of the Expires and Cache-Control headers for the document realm in question. (That is, if found in an .htaccess file, for instance, it applies only to documents generated from that directory.) If set to Off, the headers will not be generated for any document in the realm (unless overridden at a lower level, such as an .htaccess file overriding a server config file). If set to On, the headers will be added to served documents according to the criteria defined by the ExpiresByType and ExpiresDefault directives (q.v.).

Note that this directive does not guarantee that an Expires or Cache-Control 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.

ExpiresByType Directive

Description: | Value of the Expires header configured by MIME type
Syntax: | ExpiresByType MIME-type <code>seconds
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

This directive defines the value of the Expires header and the max-age directive of the Cache-Control header generated for documents of the specified type (e.g., text/html). The second argument sets the number of seconds that will be added to a base time to construct the expiration date. The Cache-Control: max-age is calculated by subtracting the request time from the expiration date and expressing the result in seconds.

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> field; M means that the file's last modification time should be used as the base time, and A means the client's access time should be used.

The difference in effect is subtle. If M 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 A 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 (i.e., the images will be accessed repeatedly within a relatively short timespan).

Example:

# enable expirations
ExpiresActive On
# expire GIF images after a month in the client's cache
ExpiresByType image/gif A2592000
# HTML documents are good for a week from the
# time they were changed
ExpiresByType text/html M604800

Note that this directive only has effect if ExpiresActive On has been specified. It overrides, for the specified MIME type only, any expiration date set by the ExpiresDefault directive.

You can also specify the expiration time calculation using an alternate syntax, described earlier in this document.

ExpiresDefault Directive

Description: | Default algorithm for calculating expiration time
Syntax: | ExpiresDefault <code>seconds
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

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 ExpiresByType directive. See the description of that directive for details about the syntax of the argument, and the alternate syntax description as well.


mod_ext_filter - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ext_filter

Description: | Pass the response body through an external program before delivery to the client
Status: | Extension
Module Identifier: | ext_filter_module
Source File: | mod_ext_filter.c

Summary

mod_ext_filter 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:

  • the programming model is much simpler
  • any programming/scripting language can be used, provided that it allows the program to read from standard input and write to standard output
  • existing programs can be used unmodified as Apache filters

Even when the performance characteristics are not suitable for production use, mod_ext_filter can be used as a prototype environment for filters.

See also

  • Filters

Examples

Generating HTML from some other type of response

# 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
</Directory>

Implementing a content encoding filter

Note: this gzip example is just for the purposes of illustration. Please refer to mod_deflate for a practical implementation.

# 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_headers directive to add
    # "Content-Encoding: gzip" header field
    Header set Content-Encoding gzip
</Location>

Slowing down the server

# 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>

Using sed to replace text in the response

# mod_ext_filter directive to define a filter which
# replaces text in the response
#
ExtFilterDefine fixtext mode=output intype=text/html \
    cmd="/bin/sed s/verdana/arial/g"

<Location "/">
    # core directive to cause the fixtext filter to
    # be run on output
    SetOutputFilter fixtext
</Location>

You can do the same thing using mod_substitute without invoking an external process.

Tracing another filter

# Trace the data read and written by mod_deflate
# for a particular client (IP 192.168.1.31)
# experiencing compression problems.
# This filter will trace what goes into mod_deflate.
ExtFilterDefine tracebefore \
    cmd="/bin/tracefilter.pl /tmp/tracebefore" \
    EnableEnv=trace_this_client

# This filter will trace what goes after mod_deflate.
# Note that without the ftype parameter, the default
# filter type of AP_FTYPE_RESOURCE would cause the
# filter to be placed *before* mod_deflate in the filter
# chain.  Giving it a numeric value slightly higher than
# AP_FTYPE_CONTENT_SET will ensure that it is placed
# after mod_deflate.
ExtFilterDefine traceafter \
    cmd="/bin/tracefilter.pl /tmp/traceafter" \
    EnableEnv=trace_this_client ftype=21

<Directory "/usr/local/docs">
    SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
    SetOutputFilter tracebefore;deflate;traceafter
</Directory>

Here is the filter which traces the data:

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
    or die "can't open $ARGV[0]: $?";

while (<STDIN>) {
    print SAVE $_;
    print $_;
}

close(SAVE);

ExtFilterDefine Directive

Description: | Define an external filter
Syntax: | ExtFilterDefine filtername parameters
Context: | server config
Status: | Extension
Module: | mod_ext_filter

The ExtFilterDefine directive defines the characteristics of an external filter, including the program to run and its arguments.

filtername 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. 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.

Subsequent parameters can appear in any order and define the external command to run and certain other characteristics. The only required parameter is cmd=. These parameters are:

cmd=cmdline
The cmd= 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 (e.g., cmd="/bin/mypgm arg1 arg2".) Normal shell quoting is not necessary since the program is run directly, bypassing the shell. Program arguments are blank-delimited. A backslash can be used to escape blanks which should be part of a program argument. Any backslashes which are part of the argument must be escaped with backslash themselves. In addition to the standard CGI environment variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and QUERY_STRING_UNESCAPED will also be set for the program.
mode=mode
Use mode=output (the default) for filters which process the response. Use mode=input for filters which process the request. mode=input is available in Apache 2.1 and later.
intype=imt
This parameter specifies the internet media type (i.e., MIME type) of documents which should be filtered. By default, all documents are filtered. If intype= is specified, the filter will be disabled for documents of other types.
outtype=imt
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.
PreservesContentLength
The PreservesContentLength 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.
ftype=filtertype
This parameter specifies the numeric value for filter type that the filter should be registered as. The default value, AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter needs to operate at a different point in the filter chain than resource filters, then this parameter will be necessary. See the AP_FTYPE_foo definitions in util_filter.h for appropriate values.
disableenv=env
This parameter specifies the name of an environment variable which, if set, will disable the filter.
enableenv=env
This parameter specifies the name of an environment variable which must be set, or the filter will be disabled.

ExtFilterOptions Directive

Description: | Configure mod_ext_filter options
Syntax: | ExtFilterOptions option [option] ...
Default: | ExtFilterOptions NoLogStderr
Context: | directory
Status: | Extension
Module: | mod_ext_filter

The ExtFilterOptions directive specifies special processing options for mod_ext_filter. Option can be one of

LogStderr | NoLogStderr
The LogStderr keyword specifies that messages written to standard error by the external filter program will be saved in the Apache error log. NoLogStderr disables this feature.
Onfail=[abort|remove]
Determines how to proceed if the external filter program cannot be started. With abort (the default value) the request will be aborted. With remove, the filter is removed and the request continues without it.
ExtFilterOptions LogStderr

Messages written to the filter's standard error will be stored in the Apache error log.


mod_file_cache - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_file_cache

Description: | Caches a static list of files in memory
Status: | Experimental
Module Identifier: | file_cache_module
Source File: | mod_file_cache.c

Summary

This module should be used with care. You can easily create a broken site using mod_file_cache, so read this document carefully.

Caching frequently requested files that change very infrequently is a technique for reducing server load. mod_file_cache provides two techniques for caching frequently requested static 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 file handle. 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.

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.

This module is an extension of and borrows heavily from the mod_mmap_static module in Apache 1.3.

Using mod_file_cache

mod_file_cache caches a list of statically configured files via MMapFile or CacheFile directives in the main server configuration.

Not all platforms support both directives. 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.

MMapFile Directive

The MMapFile directive of mod_file_cache maps a list of statically configured files into memory through the system call mmap(). This system call is available on most modern Unix derivatives, but not on all. There are sometimes system-specific limits on the size and number of files that can be mmap()ed, experimentation is probably the easiest way to find out.

This mmap()ing is done once at server start or restart, only. So whenever one of the mapped files changes on the filesystem you have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place 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 rdist and mv do this. The reason why this modules doesn't take care of changes to the files is that this check would need an extra stat() every time which is a waste and against the intent of I/O reduction.

CacheFile Directive

The CacheFile directive of mod_file_cache opens an active handle or file descriptor 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.

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 have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place 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 rdist and mv do this.

Note

Don't bother asking for a directive which recursively caches all the files in a directory. Try this instead... See the Include directive, and consider this command:

find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf

CacheFile Directive

Description: | Cache a list of file handles at startup time
Syntax: | CacheFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The CacheFile 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 re-cache them.

Be careful with the file-path 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 etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

CacheFile /usr/local/apache/htdocs/index.html

MMapFile Directive

Description: | Map a list of files into memory at startup time
Syntax: | MMapFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The MMapFile 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.

Be careful with the file-path 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 etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

MMapFile /usr/local/apache/htdocs/index.html


mod_filter - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_filter

Description: | Context-sensitive smart filter configuration module
Status: | Base
Module Identifier: | filter_module
Source File: | mod_filter.c
Compatibility: | Version 2.1 and later

Summary

This module enables smart, context-sensitive configuration of output content filters. For example, apache can be configured to process different content-types through different filters, even when the content-type is not known in advance (e.g. in a proxy).

mod_filter works by introducing indirection into the filter chain. Instead of inserting filters in the chain, we insert a filter harness which in turn dispatches conditionally to a filter provider. Any content filter may be used as a provider to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them).

Smart Filtering

In the traditional filtering model, filters are inserted unconditionally using AddOutputFilter and family. Each filter then needs to determine whether to run, and there is little flexibility available for server admins to allow the chain to be configured dynamically.

mod_filter by contrast gives server administrators a great deal of flexibility in configuring the filter chain. In fact, filters can be inserted based on complex boolean expressions This generalises the limited flexibility offered by AddOutputFilterByType.

Filter Declarations, Providers and Chains

[This image displays the traditional filter model]
Figure 1: The traditional filter model

In the traditional model, output filters are a simple chain from the content generator (handler) to the client. This works well provided the filter chain can be correctly configured, but presents problems when the filters need to be configured dynamically based on the outcome of the handler.

[This image shows the mod_filter model]
Figure 2: The mod_filter model

mod_filter works by introducing indirection into the filter chain. Instead of inserting filters in the chain, we insert a filter harness which in turn dispatches conditionally to a filter provider. Any content filter may be used as a provider to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them). There can be multiple providers for one filter, but no more than one provider will run for any single request.

A filter chain comprises any number of instances of the filter harness, each of which may have any number of providers. A special case is that of a single provider with unconditional dispatch: this is equivalent to inserting the provider filter directly into the chain.

Configuring the Chain

There are three stages to configuring a filter chain with mod_filter. For details of the directives, see below.

Declare Filters
The FilterDeclare directive declares a filter, assigning it a name and filter type. Required only if the filter is not the default type AP_FTYPE_RESOURCE.
Register Providers
The FilterProvider directive registers a provider with a filter. The filter may have been declared with FilterDeclare; if not, FilterProvider will implicitly declare it with the default type AP_FTYPE_RESOURCE. The provider must have been registered with ap_register_output_filter by some module. The final argument to FilterProvider is an expression: the provider will be selected to run for a request if and only if the expression evaluates to true. The expression may evaluate HTTP request or response headers, environment variables, or the Handler used by this request. Unlike earlier versions, mod_filter now supports complex expressions involving multiple criteria with AND / OR logic (&& / ||) and brackets. The details of the expression syntax are described in the ap_expr documentation.
Configure the Chain
The above directives build components of a smart filter chain, but do not configure it to run. The FilterChain directive builds a filter chain from smart filters declared, offering the flexibility to insert filters at the beginning or end of the chain, remove a filter, or clear the chain.

Filtering and Response Status

mod_filter normally only runs filters on responses with HTTP status 200 (OK). If you want to filter documents with other response statuses, you can set the filter-errordocs environment variable, and it will work on all responses regardless of status. To refine this further, you can use expression conditions with FilterProvider.

Upgrading from Apache HTTP Server 2.2 Configuration

The FilterProvider directive has changed from httpd 2.2: the match and dispatch arguments are replaced with a single but more versatile expression. In general, you can convert a match/dispatch pair to the two sides of an expression, using something like:

"dispatch = 'match'"

The Request headers, Response headers and Environment variables are now interpreted from syntax %{req:foo}, %{resp:foo} and %{env:foo} respectively. The variables %{HANDLER} and %{CONTENT_TYPE} are also supported.

Note that the match no longer support substring matches. They can be replaced by regular expression matches.

Examples

Server side Includes (SSI)
A simple case of replacing AddOutputFilterByType
FilterDeclare SSI
FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
FilterChain SSI
Server side Includes (SSI)
The same as the above but dispatching on handler (classic SSI behaviour; .shtml files get processed).
FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
FilterChain SSI
Emulating mod_gzip with mod_deflate
Insert INFLATE filter only if "gzip" is NOT in the Accept-Encoding header. This filter runs with ftype CONTENT_SET.
FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
FilterChain gzip
Image Downsampling
Suppose we want to downsample all web images, and have filters for GIF, JPEG and PNG.
FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'"

FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'"
<Location "/image-filter">
    FilterChain unpack downsample repack
</Location>

Protocol Handling

Historically, each filter is responsible for ensuring that whatever changes it makes are correctly represented in the HTTP response headers, and that it does not run when it would make an illegal change. This imposes a burden on filter authors to re-implement some common functionality in every filter:

  • Many filters will change the content, invalidating existing content tags, checksums, hashes, and lengths.
  • Filters that require an entire, unbroken response in input need to ensure they don't get byteranges from a backend.
  • Filters that transform output in a filter need to ensure they don't violate a Cache-Control: no-transform header from the backend.
  • Filters may make responses uncacheable.

mod_filter aims to offer generic handling of these details of filter implementation, reducing the complexity required of content filter modules. This is work-in-progress; the FilterProtocol implements some of this functionality for back-compatibility with Apache 2.0 modules. For httpd 2.1 and later, the ap_register_output_filter_protocol and ap_filter_protocol API enables filter modules to declare their own behaviour.

At the same time, mod_filter should not interfere with a filter that wants to handle all aspects of the protocol. By default (i.e. in the absence of any FilterProtocol directives), mod_filter will leave the headers untouched.

At the time of writing, this feature is largely untested, as modules in common use are designed to work with 2.0. Modules using it should test it carefully.

AddOutputFilterByType Directive

Description: | assigns an output filter to a particular media-type
Syntax: | AddOutputFilterByType filter[;filter...] media-type [media-type] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_filter
Compatibility: | Had severe limitations before being moved to mod_filter in version 2.3.7

This directive activates a particular output filter for a request depending on the response media-type.

The following example uses the DEFLATE filter, which is provided by mod_deflate. It will compress all output (either static or dynamic) which is labeled as text/html or text/plain before it is sent to the client.

AddOutputFilterByType DEFLATE text/html text/plain

If you want the content to be processed by more than one filter, their names have to be separated by semicolons. It's also possible to use one AddOutputFilterByType directive for each of these filters.

The configuration below causes all script output labeled as text/html to be processed at first by the INCLUDES filter and then by the DEFLATE filter.

<Location "/cgi-bin/">
    Options Includes
    AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>

See also

  • AddOutputFilter
  • SetOutputFilter
  • filters

FilterChain Directive

Description: | Configure the filter chain
Syntax: | FilterChain [+=-@!]filter-name ...
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This configures an actual filter chain, from declared filters. FilterChain takes any number of arguments, each optionally preceded with a single-character control that determines what to do:

+filter-name
Add filter-name to the end of the filter chain
@filter-name
Insert filter-name at the start of the filter chain
-filter-name
Remove filter-name from the filter chain
=filter-name
Empty the filter chain and insert filter-name
!
Empty the filter chain
filter-name
Equivalent to +filter-name

FilterDeclare Directive

Description: | Declare a smart filter
Syntax: | FilterDeclare filter-name [type]
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directive declares an output filter together with a header or environment variable that will determine runtime configuration. The first argument is a filter-name for use in FilterProvider, FilterChain and FilterProtocol directives.

The final (optional) argument is the type of filter, and takes values of ap_filter_type - namely RESOURCE (the default), CONTENT_SET, PROTOCOL, TRANSCODE, CONNECTION or NETWORK.

FilterProtocol Directive

Description: | Deal with correct HTTP protocol handling
Syntax: | FilterProtocol filter-name [provider-name] proto-flags
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directs mod_filter to deal with ensuring the filter doesn't run when it shouldn't, and that the HTTP response headers are correctly set taking into account the effects of the filter.

There are two forms of this directive. With three arguments, it applies specifically to a filter-name and a provider-name for that filter. With two arguments it applies to a filter-name whenever the filter runs any provider.

Flags specified with this directive are merged with the flags that underlying providers may have registerd with mod_filter. For example, a filter may internally specify the equivalent of change=yes, but a particular configuration of the module can override with change=no.

proto-flags is one or more of

change=yes|no
Specifies whether the filter changes the content, including possibly the content length. The "no" argument is supported in 2.4.7 and later.
change=1:1
The filter changes the content, but will not change the content length
byteranges=no
The filter cannot work on byteranges and requires complete input
proxy=no
The filter should not run in a proxy context
proxy=transform
The filter transforms the response in a manner incompatible with the HTTP Cache-Control: no-transform header.
cache=no
The filter renders the output uncacheable (eg by introducing randomised content changes)

FilterProvider Directive

Description: | Register a content filter
Syntax: | FilterProvider filter-name provider-name expression
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directive registers a provider for the smart filter. The provider will be called if and only if the expression declared evaluates to true when the harness is first called.

provider-name must have been registered by loading a module that registers the name with ap_register_output_filter.

expression is an ap_expr.

See also

  • Expressions in Apache HTTP Server, for a complete reference and examples.
  • mod_include

FilterTrace Directive

Description: | Get debug/diagnostic information from mod_filter
Syntax: | FilterTrace filter-name level
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_filter

This directive generates debug information from mod_filter. It is designed to help test and debug providers (filter modules), although it may also help with mod_filter itself.

The debug output depends on the level set:

0 (default)
No debug information is generated.
1
mod_filter will record buckets and brigades passing through the filter to the error log, before the provider has processed them. This is similar to the information generated by mod_diagnostics.
2 (not yet implemented)
Will dump the full data passing through to a tempfile before the provider. For single-user debug only; this will not support concurrent hits.


mod_headers - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_headers

Description: | Customization of HTTP request and response headers
Status: | Extension
Module Identifier: | headers_module
Source File: | mod_headers.c

Summary

This module provides directives to control and modify HTTP request and response headers. Headers can be merged, replaced or removed.

Order of Processing

The directives provided by mod_headers can occur almost anywhere within the server configuration, and can be limited in scope by enclosing them in configuration sections.

Order of processing is important and is affected both by the order in the configuration file and by placement in configuration sections. These two directives have a different effect if reversed:

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

This way round, the MirrorID header is not set. If reversed, the MirrorID header is set to "mirror 12".

Early and Late Processing

mod_headers can be applied either early or late in the request. The normal mode is late, when Request Headers are set immediately before running the content generator and Response Headers just as the response is sent down the wire. Always use Late mode in an operational server.

Early mode is designed as a test/debugging aid for developers. Directives defined using the early keyword are set right at the beginning of processing the request. This means they can be used to simulate different requests and set up test cases, but it also means that headers may be changed at any time by other modules before generating a Response.

Because early directives are processed before the request path's configuration is traversed, early headers can only be set in a main server or virtual host context. Early directives cannot depend on a request path, so they will fail in contexts such as <Directory> or <Location>.

Examples

  1. Copy all request headers that begin with "TS" to the response headers:
    Header echo ^TS
  2. 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.
    Header set MyHeader "%D %t"

    results in this header being added to the response:

    MyHeader: D=3775428 t=991424704447256

  3. Say hello to Joe
    Header set MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."

    results in this header being added to the response:

    MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.

  4. 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.
    SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

    If the header MyRequestHeader: myvalue is present on the HTTP request, the response will contain the following header:

    MyHeader: D=3775428 t=991424704447256 mytext

  5. Enable DAV to work with Apache running HTTP through SSL hardware (problem description) by replacing https: with http: in the Destination header:
    RequestHeader edit Destination ^https: http: early
  6. Set the same header value under multiple nonexclusive conditions, but do not duplicate the value in the final header. If all of the following conditions applied to a request (i.e., if the CGI, NO_CACHE and NO_STORE environment variables all existed for the request):
    Header merge Cache-Control no-cache env=CGI
Header merge Cache-Control no-cache env=NO_CACHE
Header merge Cache-Control no-store env=NO_STORE

    then the response would contain the following header:

    Cache-Control: no-cache, no-store

    If append was used instead of merge, then the response would contain the following header:

    Cache-Control: no-cache, no-cache, no-store

  7. Set a test cookie if and only if the client didn't send us a cookie
    Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
  8. Append a Caching header for responses with a HTTP status code of 200
    Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"

Header Directive

Description: | Configure HTTP response headers
Syntax: | Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers
Compatibility: | SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later

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 optional condition argument determines which internal table of responses headers this directive will operate against. Despite the name, the default value of onsuccess does not limit an action to responses with a 2xx status code. Headers set under this condition are still used when, for example, a request is successfully proxied or generated by CGI, even when they have generated a failing status code.

When your action is a function of an existing header, you may need to specify a condition of always, depending on which internal table the original header was set in. The table that corresponds to always is used for locally generated error responses as well as successful responses. Note also that repeating this directive with both conditions makes sense in some scenarios because always is not a superset of onsuccess with respect to existing headers:

  • You're adding a header to a locally generated non-success (non-2xx) response, such as a redirect, in which case only the table corresponding to always is used in the ultimate response.
  • You're modifying or removing a header generated by a CGI script, in which case the CGI scripts are in the table corresponding to always and not in the default table.
  • You're modifying or removing a header generated by some piece of the server but that header is not being found by the default onsuccess condition.

Separately from the condition parameter described above, you can limit an action based on HTTP status codes for e.g. proxied or CGI requests. See the example that uses %{REQUEST_STATUS} in the section above.

The action it performs is determined by the first argument (second argument if a condition is specified). This can be one of the following values:

add
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 set, append or merge should be used instead.
append
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.
echo
Request headers with this name are echoed back in the response headers. header may be a regular expression. value must be omitted.
edit
edit*
If this response header exists, its value is transformed according to a regular expression search-and-replace. The value argument is a regular expression, and the replacement is a replacement string, which may contain backreferences or format specifiers. The edit form will match and replace exactly once in a header value, whereas the edit* form will replace every instance of the search pattern if it appears more than once.
merge
The response header is appended to any existing header of the same name, unless the value to be appended already appears in the header's comma-delimited list of values. 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. Values are compared in a case sensitive manner, and after all format specifiers have been processed. Values in double quotes are considered different from otherwise identical unquoted values.
set
The response header is set, replacing any previous header with this name. The value may be a format string.
setifempty
The request header is set, but only if there is no previous header with this name.
Available in 2.4.7 and later.
unset
The response header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed. value must be omitted.
note
The value of the named response header is copied into an internal note whose name is given by value. This is useful if a header sent by a CGI or proxied resource is configured to be unset but should also be logged.
Available in 2.4.7 and later.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored for set, append, merge, add, unset and edit. The header name for echo is case sensitive and may be a regular expression.

For set, append, merge and add a value is specified as the next argument. If value contains spaces, it should be surrounded by double quotes. value may be a character string, a string containing mod_headers specific format specifiers (and character literals), or an ap_expr expression prefixed with expr=

The following format specifiers are supported in value:

Format | Description
%% | The percent sign
%t | 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=.
%D | 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=. The value is measured in microseconds.
%l | The current load averages of the actual server itself. It is designed to expose the values obtained by getloadavg() and this represents the current load average, the 5 minute average, and the 15 minute average. The value is preceded by l= with each average separated by /. Available in 2.4.4 and later.
%i | The current idle percentage of httpd (0 to 100) based on available processes and threads. The value is preceded by i=. Available in 2.4.4 and later.
%b | The current busy percentage of httpd (0 to 100) based on available processes and threads. The value is preceded by b=. Available in 2.4.4 and later.
%{VARNAME}e | The contents of the environment variable VARNAME.
%{VARNAME}s | The contents of the SSL environment variable VARNAME, if mod_ssl is enabled.

Note

The %s format specifier is only available in Apache 2.1 and later; it can be used instead of %e to avoid the overhead of enabling SSLOptions +StdEnvVars. If SSLOptions +StdEnvVars must be enabled anyway for some other reason, %e will be more efficient than %s.

Note on expression values

When the value parameter uses the ap_expr parser, some expression syntax will differ from examples that evaluate boolean expressions such as <If>:

  • The starting point of the grammar is 'string' rather than 'expr'.
  • Function calls use the %{funcname:arg} syntax rather than funcname(arg).
  • Multi-argument functions are not currently accessible from this starting point
  • Quote the entire parameter, such as
    Header set foo-checksum "expr=%{md5:foo}"

For edit there is both a value argument which is a regular expression, and an additional replacement string. As of version 2.4.7 the replacement string may also contain format specifiers.

The Header directive may be followed by an additional argument, which may be any of:

early
Specifies early processing.
env=[!]varname
The directive is applied if and only if the environment variable varname exists. A ! in front of varname reverses the test, so the directive applies only if varname is unset.
expr=expression
The directive is applied if and only if expression evaluates to true. Details of expression syntax and evaluation are documented in the ap_expr documentation.
# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

Except in early mode, the Header directives are processed just before the response is sent to the network. This means that it is possible to set and/or override most headers, except for some headers added by the HTTP header filter. Prior to 2.2.12, it was not possible to change the Content-Type header with this directive.

RequestHeader Directive

Description: | Configure HTTP request headers
Syntax: | RequestHeader add|append|edit|edit*|merge|set|setifempty|unset header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers
Compatibility: | SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later

This directive can replace, merge, change 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:

add
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 set, append or merge should be used instead.
append
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.
edit
edit*
If this request header exists, its value is transformed according to a regular expression search-and-replace. The value argument is a regular expression, and the replacement is a replacement string, which may contain backreferences or format specifiers. The edit form will match and replace exactly once in a header value, whereas the edit* form will replace every instance of the search pattern if it appears more than once.
merge
The request header is appended to any existing header of the same name, unless the value to be appended already appears in the existing header's comma-delimited list of values. 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. Values are compared in a case sensitive manner, and after all format specifiers have been processed. Values in double quotes are considered different from otherwise identical unquoted values.
set
The request header is set, replacing any previous header with this name
setifempty
The request header is set, but only if there is no previous header with this name.
Available in 2.4.7 and later.
unset
The request header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed. value must be omitted.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored. For set, append, merge and add a value is given as the third argument. If a value contains spaces, it should be surrounded by double quotes. For unset, no value should be given. value may be a character string, a string containing format specifiers or a combination of both. The supported format specifiers are the same as for the Header, please have a look there for details. For edit both a value and a replacement are required, and are a regular expression and a replacement string respectively.

The RequestHeader directive may be followed by an additional argument, which may be any of:

early
Specifies early processing.
env=[!]varname
The directive is applied if and only if the environment variable varname exists. A ! in front of varname reverses the test, so the directive applies only if varname is unset.
expr=expression
The directive is applied if and only if expression evaluates to true. Details of expression syntax and evaluation are documented in the ap_expr documentation.

Except in early mode, the RequestHeader 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.


mod_heartbeat - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_heartbeat

Description: | Sends messages with server status to frontend proxy
Status: | Experimental
Module Identifier: | heartbeat_module
Source File: | mod_heartbeat
Compatibility: | Available in Apache 2.3 and later

Summary

mod_heartbeat sends multicast messages to a mod_heartmonitor listener that advertises the servers current connection count. Usually, mod_heartmonitor will be running on a proxy server with mod_lbmethod_heartbeat loaded, which allows ProxyPass to use the "heartbeat" lbmethod inside of ProxyPass.

mod_heartbeat itself is loaded on the origin server(s) that serve requests through the proxy server(s).

To use mod_heartbeat, mod_status and mod_watchdog must be either a static modules or, if a dynamic module, must be loaded before mod_heartbeat.

Consuming mod_heartbeat Output

Every 1 second, this module generates a single multicast UDP packet, containing the number of busy and idle workers. The packet is a simple ASCII format, similar to GET query parameters in HTTP.

An Example Packet

v=1&ready=75&busy=0

Consumers should handle new variables besides busy and ready, separated by '&', being added in the future.

HeartbeatAddress Directive

Description: | Multicast address for heartbeat packets
Syntax: | HeartbeatAddress addr:port
Default: | disabled
Context: | server config
Status: | Experimental
Module: | mod_heartbeat

The HeartbeatAddress directive specifies the multicast address to which mod_heartbeat will send status information. This address will usually correspond to a configured HeartbeatListen on a frontend proxy system.

HeartbeatAddress 239.0.0.1:27999

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_heartmonitor - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_heartmonitor

Description: | Centralized monitor for mod_heartbeat origin servers
Status: | Experimental
Module Identifier: | heartmonitor_module
Source File: | mod_heartmonitor.c
Compatibility: | Available in Apache 2.3 and later

Summary

mod_heartmonitor listens for server status messages generated by mod_heartbeat enabled origin servers and makes their status available to mod_lbmethod_heartbeat. This allows ProxyPass to use the "heartbeat" lbmethod inside of ProxyPass.

This module uses the services of mod_slotmem_shm when available instead of flat-file storage. No configuration is required to use mod_slotmem_shm.

To use mod_heartmonitor, mod_status and mod_watchdog must be either a static modules or, if a dynamic module, it must be loaded before mod_heartmonitor.

HeartbeatListen Directive

Description: | multicast address to listen for incoming heartbeat requests
Syntax: | HeartbeatListenaddr:port
Default: | disabled
Context: | server config
Status: | Experimental
Module: | mod_heartmonitor

The HeartbeatListen directive specifies the multicast address on which the server will listen for status information from mod_heartbeat-enabled servers. This address will usually correspond to a configured HeartbeatAddress on an origin server.

HeartbeatListen 239.0.0.1:27999

This module is inactive until this directive is used.

HeartbeatMaxServers Directive

Description: | Specifies the maximum number of servers that will be sending heartbeat requests to this server
Syntax: | HeartbeatMaxServers number-of-servers
Default: | HeartbeatMaxServers 10
Context: | server config
Status: | Experimental
Module: | mod_heartmonitor

The HeartbeatMaxServers directive specifies the maximum number of servers that will be sending requests to this monitor server. It is used to control the size of the shared memory allocated to store the heartbeat info when mod_slotmem_shm is in use.

HeartbeatStorage Directive

Description: | Path to store heartbeat data
Syntax: | HeartbeatStorage file-path
Default: | HeartbeatStorage logs/hb.dat
Context: | server config
Status: | Experimental
Module: | mod_heartmonitor

The HeartbeatStorage directive specifies the path to store heartbeat data. This flat-file is used only when mod_slotmem_shm is not loaded.


mod_http2 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_http2

Description: | Support for the HTTP/2 transport layer
Status: | Extension
Module Identifier: | http2_module
Source File: | mod_http2.c
Compatibility: | Available in version 2.4.17 and later

Summary

This module provides HTTP/2 (RFC 7540) support for the Apache HTTP Server.

This module relies on libnghttp2 to provide the core http/2 engine.

Warning

This module is experimental. Its behaviors, directives, and defaults are subject to more change from release to release relative to other standard modules. Users are encouraged to consult the "CHANGES" file for potential updates.

You must enable HTTP/2 via Protocols in order to use the functionality described in this document:

Protocols h2 http/1.1

Environment Variables

This module can be configured to provide HTTP/2 related information as additional environment variables to the SSI and CGI namespace, as well as in custom log configurations (see %{VAR_NAME}e).

Variable Name: | Value Type: | Description:
HTTP2 | flag | HTTP/2 is being used.
H2PUSH | flag | HTTP/2 Server Push is enabled for this connection and also supported by the client.
H2_PUSH | flag | alternate name for H2PUSH
H2_PUSHED | string | empty or PUSHED for a request being pushed by the server.
H2_PUSHED_ON | number | HTTP/2 stream number that triggered the push of this request.
H2_STREAM_ID | number | HTTP/2 stream number of this request.
H2_STREAM_TAG | string | HTTP/2 process unique stream identifier, consisting of connection id and stream id separated by -.

H2Direct Directive

Description: | H2 Direct Protocol Switch
Syntax: | H2Direct on|off
Default: | H2Direct on for h2c, off for h2 protocol
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles the usage of the HTTP/2 Direct Mode. This should be used inside a <VirtualHost> section to enable direct HTTP/2 communication for that virtual host.

Direct communication means that if the first bytes received by the server on a connection match the HTTP/2 preamble, the HTTP/2 protocol is switched to immediately without further negotiation. This mode is defined in RFC 7540 for the cleartext (h2c) case. Its use on TLS connections not mandated by the standard.

When a server/vhost does not have h2 or h2c enabled via <Protocols>, the connection is never inspected for a HTTP/2 preamble. H2Direct does not matter then. This is important for connections that use protocols where an initial read might hang indefinitely, such as NNTP.

For clients that have out-of-band knowledge about a server supporting h2c, direct HTTP/2 saves the client from having to perform an HTTP/1.1 upgrade, resulting in better performance and avoiding the Upgrade restrictions on request bodies.

This makes direct h2c attractive for server to server communication as well, when the connection can be trusted or is secured by other means.

Example

H2Direct on

H2KeepAliveTimeout Directive

Description: | Timeout (in seconds) for idle HTTP/2 connections
Syntax: | H2KeepAliveTimeout seconds
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.19 and later.

This directive sets the timeout for read/write operations on idle connections where HTTP/2 is negotiated. This can be used server wide or for specific <VirtualHost>s.

This directive is similar to the <KeepAliveTimeout>, but applies only to HTTP/2 connections. A HTTP/2 connection is considered idle when no streams are open, e.g. no requests are ongoing.

By default, for non-async MPMs (prefork, worker) the keepalive timeout will be the same as H2Timeout. For async MPMs, the keepalive handling for HTTP/1 connections applies as no special action is taken.

H2MaxSessionStreams Directive

Description: | Maximum number of active streams per HTTP/2 session.
Syntax: | H2MaxSessionStreams n
Default: | H2MaxSessionStreams 100
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of active streams per HTTP/2 session (e.g. connection) that the server allows. A stream is active if it is not idle or closed according to RFC 7540.

Example

H2MaxSessionStreams 20

H2MaxWorkerIdleSeconds Directive

Description: | Maximum number of seconds h2 workers remain idle until shut down.
Syntax: | H2MaxWorkerIdleSeconds n
Default: | H2MaxWorkerIdleSeconds 600
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of seconds a h2 worker may idle until it shuts itself down. This only happens while the number of h2 workers exceeds H2MinWorkers.

Example

H2MaxWorkerIdleSeconds 20

H2MaxWorkers Directive

Description: | Maximum number of worker threads to use per child process.
Syntax: | H2MaxWorkers n
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of worker threads to spawn per child process for HTTP/2 processing. If this directive is not used, mod_http2 will chose a value suitable for the mpm module loaded.

Example

H2MaxWorkers 20

H2MinWorkers Directive

Description: | Minimal number of worker threads to use per child process.
Syntax: | H2MinWorkers n
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the minimum number of worker threads to spawn per child process for HTTP/2 processing. If this directive is not used, mod_http2 will chose a value suitable for the mpm module loaded.

Example

H2MinWorkers 10

H2ModernTLSOnly Directive

Description: | Require HTTP/2 connections to be "modern TLS" only
Syntax: | H2ModernTLSOnly on|off
Default: | H2ModernTLSOnly on
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive toggles the security checks on HTTP/2 connections in TLS mode (https:). This can be used server wide or for specific <VirtualHost>s.

The security checks require that the TSL protocol is at least TLSv1.2 and that none of the ciphers listed in RFC 7540, Appendix A is used. These checks will be extended once new security requirements come into place.

The name stems from the Security/Server Side TLS definitions at mozilla where "modern compatibility" is defined. Mozilla Firefox and other browsers require modern compatibility for HTTP/2 connections. As everything in OpSec, this is a moving target and can be expected to evolve in the future.

One purpose of having these checks in mod_http2 is to enforce this security level for all connections, not only those from browsers. The other purpose is to prevent the negotiation of HTTP/2 as a protocol should the requirements not be met.

Ultimately, the security of the TLS connection is determined by the server configuration directives for mod_ssl.

Example

H2ModernTLSOnly off

H2Push Directive

Description: | H2 Server Push Switch
Syntax: | H2Push on|off
Default: | H2Push on
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive toggles the usage of the HTTP/2 server push protocol feature. This should be used inside a <VirtualHost> section to enable direct HTTP/2 communication for that virtual host.

The HTTP/2 protocol allows the server to push other resources to a client when it asked for a particular one. This is helpful if those resources are connected in some way and the client can be expected to ask for it anyway. The pushing then saves the time it takes the client to ask for the resources itself. On the other hand, pushing resources the client never needs or already has is a waste of bandwidth.

Server pushes are detected by inspecting the Link headers of responses (see https://tools.ietf.org/html/rfc5988 for the specification). When a link thus specified has the rel=preload attribute, it is treated as a resource to be pushed.

Link headers in responses are either set by the application or can be configured via mod_headers as:

mod_headers example

<Location /index.html>
    Header add Link "</css/site.css>;rel=preload"
    Header add Link "</images/logo.jpg>;rel=preload"
</Location>

As the example shows, there can be several link headers added to a response, resulting in several pushes being triggered. There are no checks in the module to avoid pushing the same resource twice or more to one client. Use with care.

HTTP/2 server pushes are enabled by default. This directive allows it to be switch off on all resources of this server/virtual host.

Example

H2Push off

Last but not least, pushes happen only when the client signals its willingness to accept those. Most browsers do, some, like Safari 9, do not. Also, pushes also only happen for resources from the same authority as the original response is for.

H2PushDiarySize Directive

Description: | H2 Server Push Diary Size
Syntax: | H2PushDiarySize n
Default: | H2PushDiarySize 256
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.19 and later.

This directive toggles the maximum number of HTTP/2 server pushes that are remembered per HTTP/2 connection. This can be used inside the <VirtualHost> section to influence the number for all connections to that virtual host.

The push diary records a digest (currently using a 64 bit number) of pushed resources (their URL) to avoid duplicate pushes on the same connection. These value are not persisted, so clients openeing a new connection will experience known pushes again. There is ongoing work to enable a client to disclose a digest of the resources it already has, so the diary maybe initialized by the client on each connection setup.

If the maximum size is reached, newer entries replace the oldest ones. A diary entry uses 8 bytes, letting a default diary with 256 entries consume around 2 KB of memory.

A size of 0 will effectively disable the push diary.

H2PushPriority Directive

Description: | H2 Server Push Priority
Syntax: | H2PushPriority mime-type [after|before|interleaved] [weight]
Default: | H2PushPriority * After 16
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later. For having an effect, a nghttp2 library version 1.5.0 or newer is necessary.

This directive defines the priority handling of pushed responses based on the content-type of the response. This is usually defined per server config, but may also appear in a virtual host.

HTTP/2 server pushes are always related to a client request. Each such request/response pairs, or streams have a dependency and a weight, together defining the priority of a stream.

When a stream depends on another, say X depends on Y, then Y gets all bandwidth before X gets any. Note that this does not men that Y will block X. If Y has no data to send, all bandwidth allocated to Y can be used by X.

When a stream has more than one dependant, say X1 and X2 both depend on Y, the weight determines the bandwidth allocation. If X1 and X2 have the same weight, they both get half of the available bandwdith. If the weight of X1 is twice as large as that for X2, X1 gets twice the bandwidth of X2.

Ultimately, every stream depends on the root stream which gets all the bandwidht available, but never sends anything. So all its bandwidth is distributed by weight among its children. Which either have data to send or distribute the bandwidth to their own children. And so on. If none of the children have data to send, that bandwidth get distributed somewhere else according to the same rules.

The purpose of this priority system is to always make use of available bandwidth while allowing precedence and weight to be given to specific streams. Since, normally, all streams are initiated by the client, it is also the one that sets these priorities.

Only when such a stream results in a PUSH, gets the server to decide what the initial priority of such a pushed stream is. In the examples below, X is the client stream. It depends on Y and the server decides to PUSH streams P1 and P2 onto X.

The default priority rule is:

Default Priority Rule

H2PushPriority * After 16

which reads as 'Send a pushed stream of any content-type depending on the client stream with weight 16'. And so P1 and P2 will be send after X and, as they have equal weight, share bandwidth equally among themselves.

Interleaved Priority Rule

H2PushPriority text/css Interleaved 256

which reads as 'Send any CSS resource on the same dependency and weight as the client stream'. If P1 has content-type 'text/css', it will depend on Y (as does X) and its effective weight will be calculated as P1ew = Xw * (P1w / 256). With P1w being 256, this will make the effective weight the same as the weight of X. If both X and P1 have data to send, bandwidth will be allocated to both equally.

With Pw specified as 512, a pushed, interleaved stream would get double the weight of X. With 128 only half as much. Note that effective weights are always capped at 256.

Before Priority Rule

H2PushPriority application/json Before

This says that any pushed stream of content type 'application/json' should be send out before X. This makes P1 dependent on Y and X dependent on P1. So, X will be stalled as long as P1 has data to send. The effective weight is inherited from the client stream. Specifying a weight is not allowed.

Be aware that the effect of priority specifications is limited by the available server resources. If a server does not have workers available for pushed streams, the data for the stream may only ever arrive when other streams have been finished.

Last, but not least, there are some specifics of the syntax to be used in this directive:

  1. '*' is the only special content-type that matches all others. 'image/*' will not work.
  2. The default dependency is 'After'.
  3. There are also default weights: for 'After' it is 16, 'interleaved' is 256.

Shorter Priority Rules

H2PushPriority application/json 32         # an After rule
H2PushPriority image/jpeg before           # weight inherited
H2PushPriority text/css   interleaved      # weight 256 default

H2SerializeHeaders Directive

Description: | Serialize Request/Response Processing Switch
Syntax: | H2SerializeHeaders on|off
Default: | H2SerializeHeaders off
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles if HTTP/2 requests shall be serialized in HTTP/1.1 format for processing by httpd core or if received binary data shall be passed into the request_recs directly.

Serialization will lower performance, but gives more backward compatibility in case custom filters/hooks need it.

Example

H2SerializeHeaders on

H2SessionExtraFiles Directive

Description: | Number of Extra File Handles
Syntax: | H2SessionExtraFiles n
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets maximum number of extra file handles a HTTP/2 session is allowed to use. A file handle is counted as extra when it is transferred from a h2 worker thread to the main HTTP/2 connection handling. This commonly happens when serving static files.

Depending on the processing model configured on the server, the number of connections times number of active streams may exceed the number of file handles for the process. On the other hand, converting every file into memory bytes early results in too many buffer writes. This option helps to mitigate that.

The number of file handles used by a server process is then in the order of:

(h2_connections * extra_files) + (h2_max_worker)

Example

H2SessionExtraFiles 10

If nothing is configured, the module tries to make a conservative guess how many files are safe to use. This depends largely on the MPM chosen.

H2StreamMaxMemSize Directive

Description: | Maximum amount of output data buffered per stream.
Syntax: | H2StreamMaxMemSize bytes
Default: | H2StreamMaxMemSize 65536
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of outgoing data bytes buffered in memory for an active streams. This memory is not allocated per stream as such. Allocations are counted against this limit when they are about to be done. Stream processing freezes when the limit has been reached and will only continue when buffered data has been sent out to the client.

Example

H2StreamMaxMemSize 128000

H2StreamTimeout Directive

Description: | Timeout (in seconds) for idle HTTP/2 connections
Syntax: | H2StreamTimeout seconds
Default: | H2StreamTimeout 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.19 and later.

This directive sets the timeout for read/write operations on HTTP/2 streams, e.g. individual requests. This can be used server wide or for specific <VirtualHost>s.

Due to the nature of HTTP/2, which sends multiple requests over a single connection and has priority scheduling, individual streams might not see input for much longer times than HTTP/1.1 requests would.

A value of 0 enforces no timeout, so could wait on chances to receive input or write data indefinitely. This expose a server to risks of thread exhaustion.

Depending on your handling of pushed streams, priorities and general responsiveness, a site might need to increase this value. For example, if you PUSH a large resource before the requested one, the initial stream will not write until the pushed resource is fully sent.

H2Timeout Directive

Description: | Timeout (in seconds) for HTTP/2 connections
Syntax: | H2Timeout seconds
Default: | H2Timeout 5
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.19 and later.

This directive sets the timeout for read/write operations on connections where HTTP/2 is negotiated. This can be used server wide or for specific <VirtualHost>s.

This directive is similar to the <Timeout>, but applies only to HTTP/2 connections.

A value of 0 enforces no timeout.

H2TLSCoolDownSecs Directive

Description: |
Syntax: | H2TLSCoolDownSecs seconds
Default: | H2TLSCoolDownSecs 1
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive sets the number of seconds of idle time on a TLS connection before the TLS write size falls back to small (~1300 bytes) length. This can be used server wide or for specific <VirtualHost>s.

See <H2TLSWarmUpSize> for a description of TLS warmup. H2TLSCoolDownSecs reflects the fact that connections may deteriorate over time (and TCP flow adjusts) for idle connections as well. It is beneficial to overall performance to fall back to the pre-warmup phase after a number of seconds that no data has been sent.

In deployments where connections can be considered reliable, this timer can be disabled by setting it to 0.

The following example sets the seconds to zero, effectively disabling any cool down. Warmed up TLS connections stay on maximum record size.

Example

H2TLSCoolDownSecs 0

H2TLSWarmUpSize Directive

Description: |
Syntax: | H2TLSWarmUpSize amount
Default: | H2TLSWarmUpSize 1048576
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive sets the number of bytes to be sent in small TLS records (~1300 bytes) until doing maximum sized writes (16k) on https: HTTP/2 connections. This can be used server wide or for specific <VirtualHost>s.

Measurements by google performance labs show that best performance on TLS connections is reached, if initial record sizes stay below the MTU level, to allow a complete record to fit into an IP packet.

While TCP adjust its flow-control and window sizes, longer TLS records can get stuck in queues or get lost and need retransmission. This is of course true for all packets. TLS however needs the whole record in order to decrypt it. Any missing bytes at the end will stall usage of the received ones.

After a sufficient number of bytes have been send successfully, the TCP state of the connection is stable and maximum TLS record sizes (16 KB) can be used for optimal performance.

In deployments where servers are reached locally or over reliable connections only, the value might be decreased with 0 disabling any warmup phase altogether.

The following example sets the size to zero, effectively disabling any warmup phase.

Example

H2TLSWarmUpSize 0

H2Upgrade Directive

Description: | H2 Upgrade Protocol Switch
Syntax: | H2Upgrade on|off
Default: | H2Upgrade on for h2c, off for h2 protocol
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles the usage of the HTTP/1.1 Upgrade method for switching to HTTP/2. This should be used inside a <VirtualHost> section to enable Upgrades to HTTP/2 for that virtual host.

This method of switching protocols is defined in HTTP/1.1 and uses the "Upgrade" header (thus the name) to announce willingness to use another protocol. This may happen on any request of a HTTP/1.1 connection.

This method of protocol switching is enabled by default on cleartext (potential h2c) connections and disabled on TLS (potential h2), as mandated by RFC 7540.

Please be aware that Upgrades are only accepted for requests that carry no body. POSTs and PUTs with content will never trigger an upgrade to HTTP/2. See <H2Direct> for an alternative to Upgrade.

This mode only has an effect when h2 or h2c is enabled via the <Protocols>.

Example

H2Upgrade on

H2WindowSize Directive

Description: | Size of Stream Window for upstream data.
Syntax: | H2WindowSize bytes
Default: | H2WindowSize 65535
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the size of the window that is used for flow control from client to server and limits the amount of data the server has to buffer. The client will stop sending on a stream once the limit has been reached until the server announces more available space (as it has processed some of the data).

This limit affects only request bodies, not its meta data such as headers. Also, it has no effect on response bodies as the window size for those are managed by the clients.

Example

H2WindowSize 128000

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_ident - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ident

Description: | RFC 1413 ident lookups
Status: | Extension
Module Identifier: | ident_module
Source File: | mod_ident.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module queries an RFC 1413 compatible daemon on a remote host to look up the owner of a connection.

See also

  • mod_log_config

IdentityCheck Directive

Description: | Enables logging of the RFC 1413 identity of the remote user
Syntax: | IdentityCheck On|Off
Default: | IdentityCheck Off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_ident
Compatibility: | Moved out of core in Apache 2.1

This directive enables RFC 1413-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 using the %...l format string.

The information should not be trusted in any way except for rudimentary usage tracking.

Note that this can cause serious latency problems accessing your server since every request requires one of these lookups to be performed. When firewalls or proxy servers are involved, each lookup might possibly fail and add a latency duration as defined by the IdentityCheckTimeout directive to each hit. So in general this is not very useful on public servers accessible from the Internet.

IdentityCheckTimeout Directive

Description: | Determines the timeout duration for ident requests
Syntax: | IdentityCheckTimeout seconds
Default: | IdentityCheckTimeout 30
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_ident

This directive specifies the timeout duration of an ident request. The default value of 30 seconds is recommended by RFC 1413, mainly because of possible network latency. However, you may want to adjust the timeout value according to your local network speed.


mod_imagemap - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_imagemap

Description: | Server-side imagemap processing
Status: | Base
Module Identifier: | imagemap_module
Source File: | mod_imagemap.c

Summary

This module processes .map files, thereby replacing the functionality of the imagemap CGI program. Any directory or document type configured to use the handler imap-file (using either AddHandler or SetHandler) will be processed by this module.

The following directive will activate files ending with .map as imagemap files:

AddHandler imap-file map

Note that the following is still supported:

AddType application/x-httpd-imap map

However, we are trying to phase out "magic MIME types" so we are deprecating this method.

New Features

The imagemap module adds some new features that were not possible with previously distributed imagemap programs.

  • URL references relative to the Referer: information.
  • Default <base> assignment through a new map directive base.
  • No need for imagemap.conf file.
  • Point references.
  • Configurable generation of imagemap menus.

Imagemap File

The lines in the imagemap files can have one of several formats:

directive value [x,y ...]
directive value "Menu text" [x,y ...]
directive value x,y ... "Menu text"

The directive is one of base, default, poly, circle, rect, or point. The value is an absolute or relative URL, or one of the special values listed below. The coordinates are x,y 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.

Imagemap File Directives

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.

base Directive

Has the effect of <base href="value"> . The non-absolute URLs of the map-file are taken relative to this value. The base directive overrides ImapBase as set in a .htaccess file or in the server configuration files. In the absence of an ImapBase configuration directive, base defaults to http://server_name/.

base_uri is synonymous with base. Note that a trailing slash on the URL is significant.

default Directive
The action taken if the coordinates given do not fit any of the poly, circle or rect directives, and there are no point directives. Defaults to nocontent in the absence of an ImapDefault configuration setting, causing a status code of 204 No Content to be returned. The client should keep the same page displayed.
poly Directive
Takes three to one-hundred points, and is obeyed if the user selected coordinates fall within the polygon defined by these points.
circle
Takes the center coordinates of a circle and a point on the circle. Is obeyed if the user selected point is with the circle.
rect Directive
Takes the coordinates of two opposing corners of a rectangle. Obeyed if the point selected is within this rectangle.
point Directive
Takes a single point. The point directive closest to the user selected point is obeyed if no other directives are satisfied. Note that default will not be followed if a point directive is present and valid coordinates are given.

Values

The values for each of the directives can be any of the following:

a URL

The URL can be relative or absolute URL. Relative URLs can contain '..' syntax and will be resolved relative to the base value.

base itself will not be resolved according to the current value. A statement base mailto: will work properly, though.

map
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.
menu
Synonymous with map.
referer
Equivalent to the URL of the referring document. Defaults to http://servername/ if no Referer: header was present.
nocontent
Sends a status code of 204 No Content, telling the client to keep the same page displayed. Valid for all but base.
error
Fails with a 500 Server Error. Valid for all but base, but sort of silly for anything but default.

Coordinates

0,0 200,200
A coordinate consists of an x and a y 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 0,0, it is as if no coordinate had been selected.

Quoted Text

"Menu Text"

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:

<a href="http://example.com/">Menu text</a>

If no quoted text is present, the name of the link will be used as the text:

<a href="http://example.com/">http://example.com</a>

If you want to use double quotes within this text, you have to write them as &quot;.

Example Mapfile

#Comments are printed in a 'formatted' or 'semiformatted' menu.
#And can contain html tags. <hr>
base referer
poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0
rect .. 0,0 77,27 "the directory of the referer"
circle http://www.inetnebr.example.com/lincoln/feedback/ 195,0 305,27
rect another_file "in same directory as referer" 306,0 419,27
point http://www.zyzzyva.example.com/ 100,100
point http://www.tripod.example.com/ 200,200
rect mailto:nate@tripod.example.com 100,150 200,0 "Bugs?"

Referencing your mapfile

HTML example

<a href="/maps/imagemap1.map">
<img ismap src="/images/imagemap1.gif">
 </a>

XHTML example

<a href="/maps/imagemap1.map">
<img ismap="ismap" src="/images/imagemap1.gif" />
 </a>

ImapBase Directive

Description: | Default base for imagemap files
Syntax: | ImapBase map|referer|URL
Default: | ImapBase http://servername/
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imagemap

The ImapBase directive sets the default base used in the imagemap files. Its value is overridden by a base directive within the imagemap file. If not present, the base defaults to http://servername/.

See also

  • UseCanonicalName

ImapDefault Directive

Description: | Default action when an imagemap is called with coordinates that are not explicitly mapped
Syntax: | ImapDefault error|nocontent|map|referer|URL
Default: | ImapDefault nocontent
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imagemap

The ImapDefault directive sets the default default used in the imagemap files. Its value is overridden by a default directive within the imagemap file. If not present, the default action is nocontent, which means that a 204 No Content is sent to the client. In this case, the client should continue to display the original page.

ImapMenu Directive

Description: | Action if no coordinates are given when calling an imagemap
Syntax: | ImapMenu none|formatted|semiformatted|unformatted
Default: | ImapMenu formatted
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imagemap

The ImapMenu directive determines the action taken if an imagemap file is called without valid coordinates.

none
If ImapMenu is none, no menu is generated, and the default action is performed.
formatted
A formatted 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.
semiformatted
In the semiformatted 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 formatted menu.
unformatted
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.


mod_include - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_include

Description: | Server-parsed html documents (Server Side Includes)
Status: | Base
Module Identifier: | include_module
Source File: | mod_include.c

Summary

This module provides a filter which will process files before they are sent to the client. The processing is controlled by specially formatted SGML comments, referred to as elements. These elements allow conditional text, the inclusion of other files or programs, as well as the setting and printing of environment variables.

See also

  • Options
  • AcceptPathInfo
  • Filters
  • SSI Tutorial

Enabling Server-Side Includes

Server Side Includes are implemented by the INCLUDES filter. 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 text/html:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

The following directive must be given for the directories containing the shtml files (typically in a <Directory> section, but this directive is also valid in .htaccess files if AllowOverride Options is set):

Options +Includes

For backwards compatibility, the server-parsed handler also activates the INCLUDES filter. As well, Apache will activate the INCLUDES filter for any document with mime type text/x-server-parsed-html or text/x-server-parsed-html3 (and the resulting output will have the mime type text/html).

For more information, see our Tutorial on Server Side Includes.

PATH_INFO with Server Side Includes

Files processed for server-side includes no longer accept requests with PATH_INFO (trailing pathname information) by default. You can use the AcceptPathInfo directive to configure the server to accept requests with PATH_INFO.

Available Elements

The document is parsed as an HTML document, with special commands embedded as SGML comments. A command has the syntax:

<!--#element attribute=value attribute=value ... -->

The value will often be enclosed in double quotes, but single quotes (') and backticks (`) are also possible. Many commands only allow a single attribute-value pair. Note that the comment terminator (-->) should be preceded by whitespace to ensure that it isn't considered part of an SSI token. Note that the leading <!--# is one token and may not contain any whitespaces.

The allowed elements are listed in the following table:

Element | Description
config | configure output formats
echo | print variables
exec | execute external programs
fsize | print size of a file
flastmod | print last modification time of a file
include | include a file
printenv | print all available variables
set | set a value of a variable

SSI elements may be defined by modules other than mod_include. In fact, the exec element is provided by mod_cgi, and will only be available if this module is loaded.

The config Element

This command controls various aspects of the parsing. The valid attributes are:

echomsg (Apache 2.1 and later)

The value is a message that is sent back to the client if the echo element attempts to echo an undefined variable. This overrides any SSIUndefinedEcho directives.

<!--#config echomsg="[Value Undefined]" -->

errmsg

The value is a message that is sent back to the client if an error occurs while parsing the document. This overrides any SSIErrorMsg directives.

<!--#config errmsg="[Oops, something broke.]" -->

sizefmt

The value sets the format to be used when displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in Kb or Mb as appropriate, for example a size of 1024 bytes will be printed as "1K".

<!--#config sizefmt="abbrev" -->

timefmt

The value is a string to be used by the strftime(3) library routine when printing dates.

<!--#config timefmt=""%R, %B %d, %Y"" -->

The echo Element

This command prints one of the include variables defined below. If the variable is unset, the result is determined by the SSIUndefinedEcho directive. Any dates printed are subject to the currently configured timefmt.

Attributes:

var
The value is the name of the variable to print.
decoding

Specifies whether Apache should strip an encoding from the variable before processing the variable further. The default is none, where no decoding will be done. If set to url, then URL decoding (also known as %-encoding; this is appropriate for use within URLs in links, etc.) will be performed. If set to urlencoded, application/x-www-form-urlencoded compatible encoding (found in query strings) will be stripped. If set to base64, base64 will be decoded, and if set to entity, HTML entity encoding will be stripped. Decoding is done prior to any further encoding on the variable. Multiple encodings can be stripped by specifying more than one comma separated encoding. The decoding setting will remain in effect until the next decoding attribute is encountered, or the element ends.

The decoding attribute must precede the corresponding var attribute to be effective.

encoding

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. If set to urlencoded, application/x-www-form-urlencoded compatible encoding will be performed instead, and should be used with query strings. If set to base64, base64 encoding will be performed. At the start of an echo element, the default is set to entity, resulting in entity encoding (which is appropriate in the context of a block-level HTML element, e.g. a paragraph of text). This can be changed by adding an encoding attribute, which will remain in effect until the next encoding attribute is encountered or the element ends, whichever comes first.

The encoding attribute must precede the corresponding var attribute to be effective.

In order to avoid cross-site scripting issues, you should always encode user supplied data.

Example

<!--#echo encoding="entity" var="QUERY_STRING" -->

The exec Element

The exec command executes a given shell command or CGI script. It requires mod_cgi to be present in the server. If Options IncludesNOEXEC is set, this command is completely disabled. The valid attributes are:

cgi

The value specifies a (%-encoded) URL-path to the CGI script. If the path does not begin with a slash (/), 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 ScriptAlias or Options ExecCGI).

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 CGI environment.

Example

<!--#exec cgi="/cgi-bin/example.cgi" -->

If the script returns a Location: header instead of output, then this will be translated into an HTML anchor.

The include virtual element should be used in preference to exec cgi. In particular, if you need to pass additional arguments to a CGI program, using the query string, this cannot be done with exec cgi, but can be done with include virtual, as shown here:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

The server will execute the given string using /bin/sh. The include variables are available to the command, in addition to the usual set of CGI variables.

The use of #include virtual is almost always prefered to using either #exec cgi or #exec cmd. The former (#include virtual) uses the standard Apache sub-request mechanism to include files or scripts. It is much better tested and maintained.

In addition, on some platforms, like Win32, and on unix when using suexec, you cannot pass arguments to a command in an exec 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:

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

The fsize Element

This command prints the size of the specified file, subject to the sizefmt format specification. Attributes:

file
The value is a path relative to the directory containing the current document being parsed.

This file is <!--#fsize file="mod_include.html" --> bytes.

The value of file cannot start with a slash (/), nor can it contain ../ so as to refer to a file above the current directory or outside of the document root. Attempting to so will result in the error message: The given path was above the root path.
virtual
The value is a (%-encoded) URL-path. If it does not begin with a slash (/) then it is taken to be relative to the current document. Note, that this does not print the size of any CGI output, but the size of the CGI script itself.

This file is <!--#fsize virtual="/docs/mod/mod_include.html" --> bytes.

Note that in many cases these two are exactly the same thing. However, the file attribute doesn't respect URL-space aliases.

The flastmod Element

This command prints the last modification date of the specified file, subject to the timefmt format specification. The attributes are the same as for the fsize command.

The include Element

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 Options IncludesNOEXEC set, then only documents with a text MIME-type (text/plain, text/html etc.) will be included. Otherwise CGI scripts are invoked as normal using the complete URL given in the command, including any query string.

An attribute defines the location of the document, and may appear more than once in an include element; an inclusion is done for each attribute given to the include command in turn. The valid attributes are:

file
The value is a path relative to the directory containing the current document being parsed. It cannot contain ../, 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 virtual attribute should always be used in preference to this one.
virtual

The value is a (%-encoded) URL-path. 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.

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.

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:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

include virtual should be used in preference to exec cgi to include the output of CGI programs into an HTML document.

If the KeptBodySize directive is correctly configured and valid for this included file, attempts to POST requests to the enclosing HTML document will be passed through to subrequests as POST requests as well. Without the directive, all subrequests are processed as GET requests.

onerror

The value is a (%-encoded) URL-path which is shown should a previous attempt to include a file or virtual attribute failed. To be effective, this attribute must be specified after the file or virtual attributes being covered. If the attempt to include the onerror path fails, or if onerror is not specified, the default error message will be included.

# Simple example
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# Dedicated onerror paths
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

The printenv Element

This prints out a plain text listing of all existing variables and their values. Special characters are entity encoded (see the echo element for details) before being output. There are no attributes.

Example

<pre> <!--#printenv --> </pre>

The set Element

This sets the value of a variable. Attributes:

var
The name of the variable to set.
value
The value to give a variable.
decoding

Specifies whether Apache should strip an encoding from the variable before processing the variable further. The default is none, where no decoding will be done. If set to url, urlencoded, base64 or entity, URL decoding, application/x-www-form-urlencoded decoding, base64 decoding or HTML entity decoding will be performed respectively. More than one decoding can be specified by separating with commas. The decoding setting will remain in effect until the next decoding attribute is encountered, or the element ends. The decoding attribute must precede the corresponding var attribute to be effective.

encoding

Specifies how Apache should encode special characters contained in the variable before setting them. The default is none, where no encoding will be done. If set to url, urlencoding, base64 or entity, URL encoding, application/x-www-form-urlencoded encoding, base64 encoding or HTML entity encoding will be performed respectively. More than one encoding can be specified by separating with commas. The encoding setting will remain in effect until the next encoding attribute is encountered, or the element ends. The encoding attribute must precede the corresponding var attribute to be effective. Encodings are applied after all decodings have been stripped.

Example

<!--#set var="category" value="help" -->

Include Variables

In addition to the variables in the standard CGI environment, these are available for the echo command, for if and elif, and to any program invoked by the document.

DATE_GMT
The current date in Greenwich Mean Time.
DATE_LOCAL
The current date in the local time zone.
DOCUMENT_ARGS
This variable contains the query string of the active SSI document, or the empty string if a query string is not included. For subrequests invoked through the include SSI directive, QUERY_STRING will represent the query string of the subrequest and DOCUMENT_ARGS will represent the query string of the SSI document. (Available in Apache HTTP Server 2.4.19 and later.)
DOCUMENT_NAME
The filename (excluding directories) of the document requested by the user.
DOCUMENT_URI
The (%-decoded) URL path of the document requested by the user. Note that in the case of nested include files, this is not the URL for the current document. Note also that if the URL is modified internally (e.g. by an alias or directoryindex), the modified URL is shown.
LAST_MODIFIED
The last modification date of the document requested by the user.
QUERY_STRING_UNESCAPED
If a query string is present in the request for the active SSI document, this variable contains the (%-decoded) query string, which is escaped for shell usage (special characters like & etc. are preceded by backslashes). It is not set if a query string is not present. Use DOCUMENT_ARGS if shell escaping is not desired.

Variable Substitution

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 config, exec, flastmod, fsize, include, echo, and set directives. If SSILegacyExprParser is set to on, substitution also occurs in the arguments to conditional operators. You can insert a literal dollar sign into the string using backslash quoting:

<!--#set var="cur" value="\$test" -->

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, a la shell substitution:

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

This will result in the Zed variable being set to "X_Y" if REMOTE_HOST is "X" and REQUEST_METHOD is "Y".

Flow Control Elements

The basic flow control elements are:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

The if 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 elif, else or endif element is included in the output stream.

The elif or else statements are used to put text into the output stream if the original test_condition was false. These elements are optional.

The endif element ends the if element and is required.

test_condition is a boolean expression which follows the ap_expr syntax. The syntax can be changed to be compatible with Apache HTTPD 2.2.x using SSILegacyExprParser.

The SSI variables set with the var element are exported into the request environment and can be accessed with the reqenv function. As a short-cut, the function name v is also available inside mod_include.

The below example will print "from local net" if client IP address belongs to the 10.0.0.0/8 subnet.

<!--#if expr='-R "10.0.0.0/8"' -->
from local net
 <!--#else -->
from somewhere else
 <!--#endif -->

The below example will print "foo is bar" if the variable foo is set to the value "bar".

<!--#if expr='v("foo") = "bar"' -->
foo is bar
 <!--#endif -->

Reference Documentation

See also: Expressions in Apache HTTP Server, for a complete reference and examples. The restricted functions are not available inside mod_include

Legacy expression syntax

This section describes the syntax of the #if expr element if SSILegacyExprParser is set to on.

string
true if string is not empty
-A string

true if the URL represented by the string is accessible by configuration, false otherwise. This is useful where content on a page is to be hidden from users who are not authorized to view the URL, such as a link to that URL. Note that the URL is only tested for whether access would be granted, not whether the URL exists.

Example

<!--#if expr="-A /private" -->
Click <a href="/private">here</a> to access private information.
 <!--#endif -->

string1 = string2
string1 == string2
string1 != string2

Compare string1 with string2. If string2 has the form /string2/ then it is treated as a regular expression. Regular expressions are implemented by the PCRE engine and have the same syntax as those in perl 5. Note that == is just an alias for = and behaves exactly the same way.

If you are matching positive (= or ==), you can capture grouped parts of the regular expression. The captured parts are stored in the special variables $1 .. $9. The whole string matched by the regular expression is stored in the special variable $0

Example

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
 <!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2
Compare string1 with string2. Note, that strings are compared literally (using strcmp(3)). Therefore the string "100" is less than "20".
( test_condition )
true if test_condition is true
! test_condition
true if test_condition is false
test_condition1 && test_condition2
true if both test_condition1 and test_condition2 are true
test_condition1 || test_condition2
true if either test_condition1 or test_condition2 is true

"=" and "!=" bind more tightly than "&&" and "||". "!" binds most tightly. Thus, the following are equivalent:

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

The boolean operators && and || share the same priority. So if you want to bind such an operator more tightly, you should use parentheses.

Anything that's not recognized as a variable or an operator is treated as a string. Strings can also be quoted: 'string'. 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,

string1    string2 results in string1 string2

and

'string1    string2' results in string1    string2.

Optimization of Boolean Expressions

If the expressions become more complex and slow down processing significantly, you can try to optimize them according to the evaluation rules:

  • Expressions are evaluated from left to right
  • Binary boolean operators (&& and ||) are short circuited wherever possible. In conclusion with the rule above that means, mod_include evaluates at first the left expression. If the left result is sufficient to determine the end result, processing stops here. Otherwise it evaluates the right side and computes the end result from both left and right results.
  • Short circuit evaluation is turned off as long as there are regular expressions to deal with. These must be evaluated to fill in the backreference variables ($1 .. $9).

If you want to look how a particular expression is handled, you can recompile mod_include using the -DDEBUG_INCLUDE compiler option. This inserts for every parsed expression tokenizer information, the parse tree and how it is evaluated into the output sent to the client.

Escaping slashes in regex strings

All slashes which are not intended to act as delimiters in your regex must be escaped. This is regardless of their meaning to the regex engine.

SSIEndTag Directive

Description: | String that ends an include element
Syntax: | SSIEndTag tag
Default: | SSIEndTag "-->"
Context: | server config, virtual host
Status: | Base
Module: | mod_include

This directive changes the string that mod_include looks for to mark the end of an include element.

SSIEndTag "%>"

See also

  • SSIStartTag

SSIErrorMsg Directive

Description: | Error message displayed when there is an SSI error
Syntax: | SSIErrorMsg message
Default: | SSIErrorMsg "[an error occurred while processing this directive]"
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Base
Module: | mod_include

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 "<!-- Error -->" so that the message is not presented to the user.

This directive has the same effect as the <!--#config errmsg=message --> element.

SSIErrorMsg "<!-- Error -->"

SSIETag Directive

Description: | Controls whether ETags are generated by the server.
Syntax: | SSIETag on|off
Default: | SSIETag off
Context: | directory, .htaccess
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.2.15 and later.

Under normal circumstances, a file filtered by mod_include may contain elements that are either dynamically generated, or that may have changed independently of the original file. As a result, by default the server is asked not to generate an ETag header for the response by adding no-etag to the request notes.

The SSIETag directive suppresses this behaviour, and allows the server to generate an ETag header. This can be used to enable caching of the output. Note that a backend server or dynamic content generator may generate an ETag of its own, ignoring no-etag, and this ETag will be passed by mod_include regardless of the value of this setting. SSIETag can take on the following values:

off
no-etag will be added to the request notes, and the server is asked not to generate an ETag. Where a server ignores the value of no-etag and generates an ETag anyway, the ETag will be respected.
on
Existing ETags will be respected, and ETags generated by the server will be passed on in the response.

SSILastModified Directive

Description: | Controls whether Last-Modified headers are generated by the server.
Syntax: | SSILastModified on|off
Default: | SSILastModified off
Context: | directory, .htaccess
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.2.15 and later.

Under normal circumstances, a file filtered by mod_include may contain elements that are either dynamically generated, or that may have changed independently of the original file. As a result, by default the Last-Modified header is stripped from the response.

The SSILastModified directive overrides this behaviour, and allows the Last-Modified header to be respected if already present, or set if the header is not already present. This can be used to enable caching of the output. SSILastModified can take on the following values:

off
The Last-Modified header will be stripped from responses, unless the XBitHack directive is set to full as described below.
on
The Last-Modified header will be respected if already present in a response, and added to the response if the response is a file and the header is missing. The SSILastModified directive takes precedence over XBitHack.

SSILegacyExprParser Directive

Description: | Enable compatibility mode for conditional expressions.
Syntax: | SSILegacyExprParser on|off
Default: | SSILegacyExprParser off
Context: | directory, .htaccess
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.3.13 and later.

As of version 2.3.13, mod_include has switched to the new ap_expr syntax for conditional expressions in #if flow control elements. This directive allows to switch to the old syntax which is compatible with Apache HTTPD version 2.2.x and earlier.

SSIStartTag Directive

Description: | String that starts an include element
Syntax: | SSIStartTag tag
Default: | SSIStartTag "<!--#"
Context: | server config, virtual host
Status: | Base
Module: | mod_include

This directive changes the string that mod_include looks for to mark an include element to process.

You may want to use this option if you have 2 servers parsing the output of a file each processing different commands (possibly at different times).

      SSIStartTag "<%"

      SSIEndTag   "%>"

The example given above, which also specifies a matching SSIEndTag, will allow you to use SSI directives as shown in the example below:

SSI directives with alternate start and end tags

<%printenv %>

See also

  • SSIEndTag

SSITimeFormat Directive

Description: | Configures the format in which date strings are displayed
Syntax: | SSITimeFormat formatstring
Default: | SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Base
Module: | mod_include

This directive changes the format in which date strings are displayed when echoing DATE environment variables. The formatstring is as in strftime(3) from the C standard library.

This directive has the same effect as the <!--#config timefmt=formatstring --> element.

SSITimeFormat "%R, %B %d, %Y"

The above directive would cause times to be displayed in the format "22:26, June 14, 2002".

SSIUndefinedEcho Directive

Description: | String displayed when an unset variable is echoed
Syntax: | SSIUndefinedEcho string
Default: | SSIUndefinedEcho "(none)"
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Base
Module: | mod_include

This directive changes the string that mod_include displays when a variable is not set and "echoed".

SSIUndefinedEcho "<!-- undef -->"

XBitHack Directive

Description: | Parse SSI directives in files with the execute bit set
Syntax: | XBitHack on|off|full
Default: | XBitHack off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_include

The XBitHack directive controls the parsing of ordinary html documents. This directive only affects files associated with the MIME-type text/html. XBitHack can take on the following values:

off
No special treatment of executable files.
on
Any text/html file that has the user-execute bit set will be treated as a server-parsed html document.
full
As for on 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.

Note

You would not want to use the full option, unless you assure the group-execute bit is unset for every SSI script which might #include a CGI or otherwise produces different output on each hit (or could potentially change on subsequent requests).

The SSILastModified directive takes precedence over the XBitHack directive when SSILastModified is set to on.


mod_info - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_info

Description: | Provides a comprehensive overview of the server configuration
Status: | Extension
Module Identifier: | info_module
Source File: | mod_info.c

Summary

To configure mod_info, add the following to your httpd.conf file.

<Location "/server-info">
    SetHandler server-info
</Location>

You may wish to use mod_authz_host inside the <Location> directive to limit access to your server configuration information:

<Location "/server-info">
    SetHandler server-info
    Require host example.com
</Location>

Once configured, the server information is obtained by accessing http://your.host.example.com/server-info

Security Issues

Once mod_info is loaded into the server, its handler capability is available in all configuration files, including per-directory files (e.g., .htaccess). This may have security-related ramifications for your site.

In particular, this module can leak sensitive information from the configuration directives of other Apache modules such as system paths, usernames/passwords, database names, etc. Therefore, this module should only be used in a controlled environment and always with caution.

You will probably want to use mod_authz_host to limit access to your server configuration information.

Access control

<Location "/server-info">
    SetHandler server-info
    # Allow access from server itself
    Require ip 127.0.0.1

    # Additionally, allow access from local workstation
    Require ip 192.168.1.17
</Location>

Selecting the information shown

By default, the server information includes a list of all enabled modules, and for each module, a description of the directives understood by that module, the hooks implemented by that module, and the relevant directives from the current configuration.

Other views of the configuration information are available by appending a query to the server-info request. For example, http://your.host.example.com/server-info?config will show all configuration directives.

?<module-name>
Only information relevant to the named module
?config
Just the configuration directives, not sorted by module
?hooks
Only the list of Hooks each module is attached to
?list
Only a simple list of enabled modules
?server
Only the basic server information

Dumping the configuration on startup

If the config define -DDUMP_CONFIG is set, mod_info will dump the pre-parsed configuration to stdout during server startup. Pre-parsed means that directives like <IfDefine> and <IfModule> are evaluated and environment varialbles are replaced. However it does not represent the final state of the configuration. In particular, it does not represent the merging or overriding that may happen for repeated directives.

This is roughly equivalent to the ?config query.

Known Limitations

mod_info provides its information by reading the parsed configuration, rather than reading the original configuration file. There are a few limitations as a result of the way the parsed configuration tree is created:

  • Directives which are executed immediately rather than being stored in the parsed configuration are not listed. These include ServerRoot, LoadModule, and LoadFile.
  • Directives which control the configuration file itself, such as Include, <IfModule> and <IfDefine> are not listed, but the included configuration directives are.
  • Comments are not listed. (This may be considered a feature.)
  • Configuration directives from .htaccess files are not listed (since they do not form part of the permanent server configuration).
  • Container directives such as <Directory> are listed normally, but mod_info cannot figure out the line number for the closing </Directory>.
  • Directives generated by third party modules such as mod_perl might not be listed.

AddModuleInfo Directive

Description: | Adds additional information to the module information displayed by the server-info handler
Syntax: | AddModuleInfo module-name string
Context: | server config, virtual host
Status: | Extension
Module: | mod_info

This allows the content of string to be shown as HTML interpreted, Additional Information for the module module-name. Example:

AddModuleInfo mod_deflate.c 'See <a \
    href="http://httpd.apache.org/docs/2.4/mod/mod_deflate.html">\
    http://httpd.apache.org/docs/2.4/mod/mod_deflate.html</a>'


mod_isapi - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_isapi

Description: | ISAPI Extensions within Apache for Windows
Status: | Base
Module Identifier: | isapi_module
Source File: | mod_isapi.c
Compatibility: | Win32 only

Summary

This module implements the Internet Server extension API. It allows Internet Server extensions (e.g. ISAPI .dll modules) to be served by Apache for Windows, subject to the noted restrictions.

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 extension. Please do not post such problems to Apache's lists or bug reporting pages.

Usage

In the server configuration file, use the AddHandler directive to associate ISAPI files with the isapi-handler handler, and map it to them with their file extensions. To enable any .dll file to be processed as an ISAPI extension, edit the httpd.conf file and add the following line:

AddHandler isapi-handler .dll
In older versions of the Apache server, isapi-isa was the proper handler name, rather than isapi-handler. As of 2.3 development versions of the Apache server, isapi-isa is no longer valid. You will need to change your configuration to use isapi-handler instead.

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:

ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

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, Options ExecCGI must be set for the directory that contains the ISAPI .dll file.

Review the Additional Notes and the Programmer's Journal for additional details and clarification of the specific ISAPI support offered by mod_isapi.

Additional Notes

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 ISAPILogNotSupported Off exists to quiet this noise.

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.

Also, remember that while Apache supports ISAPI Extensions, it does not support ISAPI Filters. Support for filters may be added at a later date, but no support is planned at this time.

Programmer's Journal

If you are programming Apache 2.0 mod_isapi modules, you must limit your calls to ServerSupportFunction to the following directives:

HSE_REQ_SEND_URL_REDIRECT_RESP
Redirect the user to another location.
This must be a fully qualified URL (e.g. http://server/location).
HSE_REQ_SEND_URL
Redirect the user to another location.
This cannot be a fully qualified URL, you are not allowed to pass the protocol or a server name (e.g. simply /location).
This redirection is handled by the server, not the browser.

Warning

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.

HSE_REQ_SEND_RESPONSE_HEADER
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.
HSE_REQ_DONE_WITH_SESSION
Apache considers this a no-op, since the session will be finished when the ISAPI returns from processing.
HSE_REQ_MAP_URL_TO_PATH
Apache will translate a virtual name to a physical name.
HSE_APPEND_LOG_PARAMETER
This logged message may be captured in any of the following logs:
  • in the \"%{isapi-parameter}n\" component in a CustomLog directive
  • in the %q log component with the ISAPIAppendLogToQuery On directive
  • in the error log with the ISAPIAppendLogToErrors On directive

The first option, the %{isapi-parameter}n component, is always available and preferred.

HSE_REQ_IS_KEEP_CONN
Will return the negotiated Keep-Alive status.
HSE_REQ_SEND_RESPONSE_HEADER_EX
Will behave as documented, although the fKeepConn flag is ignored.
HSE_REQ_IS_CONNECTED
Will report false if the request has been aborted.

Apache returns FALSE to any unsupported call to ServerSupportFunction, and sets the GetLastError value to ERROR_INVALID_PARAMETER.

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.

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.

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.

Since httpd 2.0, mod_isapi 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 httpd also supports preloading ISAPI .dlls for performance.

ISAPIAppendLogToErrors Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
Syntax: | ISAPIAppendLogToErrors on|off
Default: | ISAPIAppendLogToErrors off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the server error log.

ISAPIAppendLogToQuery Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
Syntax: | ISAPIAppendLogToQuery on|off
Default: | ISAPIAppendLogToQuery on
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field (appended to the CustomLog %q component).

ISAPICacheFile Directive

Description: | ISAPI .dll files to be loaded at startup
Syntax: | ISAPICacheFile file-path [file-path] ...
Context: | server config, virtual host
Status: | Base
Module: | mod_isapi

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. If the path name is not absolute, it will be treated relative to ServerRoot.

ISAPIFakeAsync Directive

Description: | Fake asynchronous support for ISAPI callbacks
Syntax: | ISAPIFakeAsync on|off
Default: | ISAPIFakeAsync off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

While set to on, asynchronous support for ISAPI callbacks is simulated.

ISAPILogNotSupported Directive

Description: | Log unsupported feature requests from ISAPI extensions
Syntax: | ISAPILogNotSupported on|off
Default: | ISAPILogNotSupported off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Logs all requests for unsupported features from ISAPI extensions in the server error log. This may help administrators to track down problems. Once set to on and all desired ISAPI modules are functioning, it should be set back to off.

ISAPIReadAheadBuffer Directive

Description: | Size of the Read Ahead Buffer sent to ISAPI extensions
Syntax: | ISAPIReadAheadBuffer size
Default: | ISAPIReadAheadBuffer 49152
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

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.


mod_lbmethod_bybusyness - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_lbmethod_bybusyness

Description: | Pending Request Counting load balancer scheduler algorithm for mod_proxy_balancer
Status: | Extension
Module Identifier: | lbmethod_bybusyness_module
Source File: | mod_lbmethod_bybusyness.c
Compatibility: | Split off from mod_proxy_balancer in 2.3

Summary

This module does not provide any configuration directives of its own. It requires the services of mod_proxy_balancer, and provides the bybusyness load balancing method.

See also

  • mod_proxy
  • mod_proxy_balancer

Pending Request Counting Algorithm

Enabled via lbmethod=bybusyness, this scheduler keeps track of how many requests each worker is currently assigned at present. A new request is automatically assigned to the worker with the lowest number of active requests. This is useful in the case of workers that queue incoming requests independently of Apache, to ensure that queue length stays even and a request is always given to the worker most likely to service it the fastest and reduce latency.

In the case of multiple least-busy workers, the statistics (and weightings) used by the Request Counting method are used to break the tie. Over time, the distribution of work will come to resemble that characteristic of byrequests (as implemented by mod_lbmethod_byrequests).


mod_lbmethod_byrequests - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_lbmethod_byrequests

Description: | Request Counting load balancer scheduler algorithm for mod_proxy_balancer
Status: | Extension
Module Identifier: | lbmethod_byrequests_module
Source File: | mod_lbmethod_byrequests.c
Compatibility: | Split off from mod_proxy_balancer in 2.3

Summary

This module does not provide any configuration directives of its own. It requires the services of mod_proxy_balancer, and provides the byrequests load balancing method..

See also

  • mod_proxy
  • mod_proxy_balancer

Request Counting Algorithm

Enabled via lbmethod=byrequests, the idea behind this scheduler is that we distribute the requests among the various workers to ensure that each gets their configured share of the number of requests. It works as follows:

lbfactor is how much we expect this worker to work, or the workers' work quota. This is a normalized value representing their "share" of the amount of work to be done.

lbstatus is how urgent this worker has to work to fulfill its quota of work.

The worker is a member of the load balancer, usually a remote host serving one of the supported protocols.

We distribute each worker's work quota to the worker, and then look which of them needs to work most urgently (biggest lbstatus). This worker is then selected for work, and its lbstatus reduced by the total work quota we distributed to all workers. Thus the sum of all lbstatus does not change(*) and we distribute the requests as desired.

If some workers are disabled, the others will still be scheduled correctly.

for each worker in workers
    worker lbstatus += worker lbfactor
    total factor    += worker lbfactor
    if worker lbstatus > candidate lbstatus
        candidate = worker

candidate lbstatus -= total factor

If a balancer is configured as follows:

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25
lbstatus | 0 | 0 | 0 | 0

And b gets disabled, the following schedule is produced:

worker | a | b | c | d
lbstatus | -50 | 0 | 25 | 25
lbstatus | -25 | 0 | -25 | 50
lbstatus | 0 | 0 | 0 | 0
(repeat)

That is it schedules: a c d a c d a c d ... Please note that:

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25

Has the exact same behavior as:

worker | a | b | c | d
lbfactor | 1 | 1 | 1 | 1

This is because all values of lbfactor are normalized with respect to the others. For:

worker | a | b | c
lbfactor | 1 | 4 | 1

worker b will, on average, get 4 times the requests that a and c will.

The following asymmetric configuration works as one would expect:

worker | a | b
lbfactor | 70 | 30
lbstatus | -30 | 30
lbstatus | 40 | -40
lbstatus | 10 | -10
lbstatus | -20 | 20
lbstatus | -50 | 50
lbstatus | 20 | -20
lbstatus | -10 | 10
lbstatus | -40 | 40
lbstatus | 30 | -30
lbstatus | 0 | 0
(repeat)

That is after 10 schedules, the schedule repeats and 7 a are selected with 3 b interspersed.


mod_lbmethod_bytraffic - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_lbmethod_bytraffic

Description: | Weighted Traffic Counting load balancer scheduler algorithm for mod_proxy_balancer
Status: | Extension
Module Identifier: | lbmethod_bytraffic_module
Source File: | mod_lbmethod_bytraffic.c
Compatibility: | Split off from mod_proxy_balancer in 2.3

Summary

This module does not provide any configuration directives of its own. It requires the services of mod_proxy_balancer, and provides the bytraffic load balancing method..

See also

  • mod_proxy
  • mod_proxy_balancer

Weighted Traffic Counting Algorithm

Enabled via lbmethod=bytraffic, the idea behind this scheduler is very similar to the Request Counting method, with the following changes:

lbfactor is how much traffic, in bytes, we want this worker to handle. This is also a normalized value representing their "share" of the amount of work to be done, but instead of simply counting the number of requests, we take into account the amount of traffic this worker has either seen or produced.

If a balancer is configured as follows:

worker | a | b | c
lbfactor | 1 | 2 | 1

Then we mean that we want b to process twice the amount of bytes than a or c should. It does not necessarily mean that b would handle twice as many requests, but it would process twice the I/O. Thus, the size of the request and response are applied to the weighting and selection algorithm.

Note: input and output bytes are weighted the same.


mod_lbmethod_heartbeat - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_lbmethod_heartbeat

Description: | Heartbeat Traffic Counting load balancer scheduler algorithm for mod_proxy_balancer
Status: | Experimental
Module Identifier: | lbmethod_heartbeat_module
Source File: | mod_lbmethod_heartbeat.c
Compatibility: | Available in version 2.3 and later

Summary

lbmethod=heartbeat uses the services of mod_heartmonitor to balance between origin servers that are providing heartbeat info via the mod_heartbeat module.

This modules load balancing algorithm favors servers with more ready (idle) capacity over time, but does not select the server with the most ready capacity every time. Servers that have 0 active clients are penalized, with the assumption that they are not fully initialized.

See also

  • mod_proxy
  • mod_proxy_balancer
  • mod_heartbeat
  • mod_heartmonitor

HeartbeatStorage Directive

Description: | Path to read heartbeat data
Syntax: | HeartbeatStorage file-path
Default: | HeartbeatStorage logs/hb.dat
Context: | server config
Status: | Experimental
Module: | mod_lbmethod_heartbeat

The HeartbeatStorage directive specifies the path to read heartbeat data. This flat-file is used only when mod_slotmem_shm is not loaded.


mod_ldap - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ldap

Description: | LDAP connection pooling and result caching services for use by other LDAP modules
Status: | Extension
Module Identifier: | ldap_module
Source File: | util_ldap.c

Summary

This module was created to improve the performance of websites relying on backend connections to LDAP servers. In addition to the functions provided by the standard LDAP libraries, this module adds an LDAP connection pool and an LDAP shared memory cache.

To enable this module, LDAP support must be compiled into apr-util. This is achieved by adding the --with-ldap flag to the configure script when building Apache.

SSL/TLS support is dependent on which LDAP toolkit has been linked to APR. As of this writing, APR-util supports: OpenLDAP SDK (2.x or later), Novell LDAP SDK, Mozilla LDAP SDK, native Solaris LDAP SDK (Mozilla based) or the native Microsoft LDAP SDK. See the APR website for details.

Example Configuration

The following is an example configuration that uses mod_ldap to increase the performance of HTTP Basic authentication provided by mod_authnz_ldap.

# Enable the LDAP connection pool and shared
# memory cache. Enable the LDAP cache status
# handler. Requires that mod_ldap and mod_authnz_ldap
# be loaded. Change the "yourdomain.example.com" to
# match your domain.

LDAPSharedCacheSize 500000
LDAPCacheEntries 1024
LDAPCacheTTL 600
LDAPOpCacheEntries 1024
LDAPOpCacheTTL 600

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

LDAP Connection Pool

LDAP connections are pooled from request to request. This allows the LDAP server to remain connected and bound ready for the next request, without the need to unbind/connect/rebind. The performance advantages are similar to the effect of HTTP keepalives.

On a busy server it is possible that many requests will try and access the same LDAP server connection simultaneously. Where an LDAP connection is in use, Apache will create a new connection alongside the original one. This ensures that the connection pool does not become a bottleneck.

There is no need to manually enable connection pooling in the Apache configuration. Any module using this module for access to LDAP services will share the connection pool.

LDAP connections can keep track of the ldap client credentials used when binding to an LDAP server. These credentials can be provided to LDAP servers that do not allow anonymous binds during referral chasing. To control this feature, see the LDAPReferrals and LDAPReferralHopLimit directives. By default, this feature is enabled.

LDAP Cache

For improved performance, mod_ldap uses an aggressive caching strategy to minimize the number of times that the LDAP server must be contacted. Caching can easily double or triple the throughput of Apache when it is serving pages protected with mod_authnz_ldap. In addition, the load on the LDAP server will be significantly decreased.

mod_ldap supports two types of LDAP caching during the search/bind phase with a search/bind cache and during the compare phase with two operation caches. Each LDAP URL that is used by the server has its own set of these three caches.

The Search/Bind Cache

The process of doing a search and then a bind is the most time-consuming aspect of LDAP operation, especially if the directory is large. The search/bind cache is used to cache all searches that resulted in successful binds. Negative results (i.e., unsuccessful searches, or searches that did not result in a successful bind) are not cached. The rationale behind this decision is that connections with invalid credentials are only a tiny percentage of the total number of connections, so by not caching invalid credentials, the size of the cache is reduced.

mod_ldap stores the username, the DN retrieved, the password used to bind, and the time of the bind in the cache. Whenever a new connection is initiated with the same username, mod_ldap compares the password of the new connection with the password in the cache. If the passwords match, and if the cached entry is not too old, mod_ldap bypasses the search/bind phase.

The search and bind cache is controlled with the LDAPCacheEntries and LDAPCacheTTL directives.

Operation Caches

During attribute and distinguished name comparison functions, mod_ldap uses two operation caches to cache the compare operations. The first compare cache is used to cache the results of compares done to test for LDAP group membership. The second compare cache is used to cache the results of comparisons done between distinguished names.

Note that, when group membership is being checked, any sub-group comparison results are cached to speed future sub-group comparisons.

The behavior of both of these caches is controlled with the LDAPOpCacheEntries and LDAPOpCacheTTL directives.

Monitoring the Cache

mod_ldap has a content handler that allows administrators to monitor the cache performance. The name of the content handler is ldap-status, so the following directives could be used to access the mod_ldap cache information:

<Location "/server/cache-info">
    SetHandler ldap-status
</Location>

By fetching the URL http://servername/cache-info, the administrator can get a status report of every cache that is used by mod_ldap cache. Note that if Apache does not support shared memory, then each httpd instance has its own cache, so reloading the URL will result in different information each time, depending on which httpd instance processes the request.

Using SSL/TLS

The ability to create an SSL and TLS connections to an LDAP server is defined by the directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode. These directives specify the CA and optional client certificates to be used, as well as the type of encryption to be used on the connection (none, SSL or TLS/STARTTLS).

# Establish an SSL LDAP connection on port 636. Requires that
# mod_ldap and mod_authnz_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedGlobalCert CA_DER "/certs/certfile.der"

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>
# Establish a TLS LDAP connection on port 389. Requires that
# mod_ldap and mod_authnz_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedGlobalCert CA_DER "/certs/certfile.der:

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one" TLS
    Require valid-user
</Location>

SSL/TLS Certificates

The different LDAP SDKs have widely different methods of setting and handling both CA and client side certificates.

If you intend to use SSL or TLS, read this section CAREFULLY so as to understand the differences between configurations on the different LDAP toolkits supported.

Netscape/Mozilla/iPlanet SDK

CA certificates are specified within a file called cert7.db. The SDK will not talk to any LDAP server whose certificate was not signed by a CA specified in this file. If client certificates are required, an optional key3.db file may be specified with an optional password. The secmod file can be specified if required. These files are in the same format as used by the Netscape Communicator or Mozilla web browsers. The easiest way to obtain these files is to grab them from your browser installation.

Client certificates are specified per connection using the LDAPTrustedClientCert directive by referring to the certificate "nickname". An optional password may be specified to unlock the certificate's private key.

The SDK supports SSL only. An attempt to use STARTTLS will cause an error when an attempt is made to contact the LDAP server at runtime.

# Specify a Netscape CA certificate file
LDAPTrustedGlobalCert CA_CERT7_DB "/certs/cert7.db"
# Specify an optional key3.db file for client certificate support
LDAPTrustedGlobalCert CERT_KEY3_DB "/certs/key3.db"
# Specify the secmod file if required
LDAPTrustedGlobalCert CA_SECMOD "/certs/secmod"
<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

Novell SDK

One or more CA certificates must be specified for the Novell SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.

Note: Client certificates are specified globally rather than per connection, and so must be specified with the LDAPTrustedGlobalCert directive as below. Trying to set client certificates via the LDAPTrustedClientCert directive will cause an error to be logged when an attempt is made to connect to the LDAP server..

The SDK supports both SSL and STARTTLS, set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced, override this directive.

# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
# Specify a client certificate file and key
LDAPTrustedGlobalCert CERT_BASE64 "/certs/cert1.pem"
LDAPTrustedGlobalCert KEY_BASE64 "/certs/key1.pem" [password]
# Do not use this directive, as it will throw an error
#LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"

OpenLDAP SDK

One or more CA certificates must be specified for the OpenLDAP SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.

Both CA and client certificates may be specified globally (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert). When any settings are specified per-connection, the global settings are superceded.

The documentation for the SDK claims to support both SSL and STARTTLS, however STARTTLS does not seem to work on all versions of the SDK. The SSL/TLS mode can be set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced. The OpenLDAP documentation notes that SSL (ldaps://) support has been deprecated to be replaced with TLS, although the SSL functionality still works.

# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"
    LDAPTrustedClientCert KEY_BASE64 "/certs/key1.pem"
    # CA certs respecified due to per-directory client certs
    LDAPTrustedClientCert CA_DER "/certs/cacert1.der"
    LDAPTrustedClientCert CA_BASE64 "/certs/cacert2.pem"
    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

Solaris SDK

SSL/TLS for the native Solaris LDAP libraries is not yet supported. If required, install and use the OpenLDAP libraries instead.

Microsoft SDK

SSL/TLS certificate configuration for the native Microsoft LDAP libraries is done inside the system registry, and no configuration directives are required.

Both SSL and TLS are supported by using the ldaps:// URL format, or by using the LDAPTrustedMode directive accordingly.

Note: The status of support for client certificates is not yet known for this toolkit.

LDAPCacheEntries Directive

Description: | Maximum number of entries in the primary LDAP cache
Syntax: | LDAPCacheEntries number
Default: | LDAPCacheEntries 1024
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the maximum size of the primary LDAP cache. This cache contains successful search/binds. Set it to 0 to turn off search/bind caching. The default size is 1024 cached searches.

LDAPCacheTTL Directive

Description: | Time that cached items remain valid
Syntax: | LDAPCacheTTL seconds
Default: | LDAPCacheTTL 600
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the time (in seconds) that an item in the search/bind cache remains valid. The default is 600 seconds (10 minutes).

LDAPConnectionPoolTTL Directive

Description: | Discard backend connections that have been sitting in the connection pool too long
Syntax: | LDAPConnectionPoolTTL n
Default: | LDAPConnectionPoolTTL -1
Context: | server config, virtual host
Status: | Extension
Module: | mod_ldap
Compatibility: | Apache HTTP Server 2.3.12 and later

Specifies the maximum age, in seconds, that a pooled LDAP connection can remain idle and still be available for use. Connections are cleaned up when they are next needed, not asynchronously.

A setting of 0 causes connections to never be saved in the backend connection pool. The default value of -1, and any other negative value, allows connections of any age to be reused.

For performance reasons, the reference time used by this directive is based on when the LDAP connection is returned to the pool, not the time of the last successful I/O with the LDAP server.

Since 2.4.10, new measures are in place to avoid the reference time from being inflated by cache hits or slow requests. First, the reference time is not updated if no backend LDAP conncetions were needed. Second, the reference time uses the time the HTTP request was received instead of the time the request is completed.

This timeout defaults to units of seconds, but accepts suffixes for milliseconds (ms), minutes (min), and hours (h).

LDAPConnectionTimeout Directive

Description: | Specifies the socket connection timeout in seconds
Syntax: | LDAPConnectionTimeout seconds
Context: | server config
Status: | Extension
Module: | mod_ldap

This directive configures the LDAP_OPT_NETWORK_TIMEOUT (or LDAP_OPT_CONNECT_TIMEOUT) option in the underlying LDAP client library, when available. This value typically controls how long the LDAP client library will wait for the TCP connection to the LDAP server to complete.

If a connection is not successful with the timeout period, either an error will be returned or the LDAP client library will attempt to connect to a secondary LDAP server if one is specified (via a space-separated list of hostnames in the AuthLDAPURL).

The default is 10 seconds, if the LDAP client library linked with the server supports the LDAP_OPT_NETWORK_TIMEOUT option.

LDAPConnectionTimeout is only available when the LDAP client library linked with the server supports the LDAP_OPT_NETWORK_TIMEOUT (or LDAP_OPT_CONNECT_TIMEOUT) option, and the ultimate behavior is dictated entirely by the LDAP client library.

LDAPLibraryDebug Directive

Description: | Enable debugging in the LDAP SDK
Syntax: | LDAPLibraryDebug 7
Default: | disabled
Context: | server config
Status: | Extension
Module: | mod_ldap

Turns on SDK-specific LDAP debug options that generally cause the LDAP SDK to log verbose trace information to the main Apache error log. The trace messages from the LDAP SDK provide gory details that can be useful during debugging of connectivity problems with backend LDAP servers

This option is only configurable when Apache HTTP Server is linked with an LDAP SDK that implements LDAP_OPT_DEBUG or LDAP_OPT_DEBUG_LEVEL, such as OpenLDAP (a value of 7 is verbose) or Tivoli Directory Server (a value of 65535 is verbose).

The logged information will likely contain plaintext credentials being used or validated by LDAP authentication, so care should be taken in protecting and purging the error log when this directive is used.

LDAPOpCacheEntries Directive

Description: | Number of entries used to cache LDAP compare operations
Syntax: | LDAPOpCacheEntries number
Default: | LDAPOpCacheEntries 1024
Context: | server config
Status: | Extension
Module: | mod_ldap

This specifies the number of entries mod_ldap will use to cache LDAP compare operations. The default is 1024 entries. Setting it to 0 disables operation caching.

LDAPOpCacheTTL Directive

Description: | Time that entries in the operation cache remain valid
Syntax: | LDAPOpCacheTTL seconds
Default: | LDAPOpCacheTTL 600
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the time (in seconds) that entries in the operation cache remain valid. The default is 600 seconds.

LDAPReferralHopLimit Directive

Description: | The maximum number of referral hops to chase before terminating an LDAP query.
Syntax: | LDAPReferralHopLimit number
Default: | SDK dependent, typically between 5 and 10
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ldap

This directive, if enabled by the LDAPReferrals directive, limits the number of referral hops that are followed before terminating an LDAP query.

Support for this tunable is uncommon in LDAP SDKs.

LDAPReferrals Directive

Description: | Enable referral chasing during queries to the LDAP server.
Syntax: | LDAPReferrals On|Off|default
Default: | LDAPReferrals On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ldap
Compatibility: | The default parameter is available in Apache 2.4.7 and later

Some LDAP servers divide their directory among multiple domains and use referrals to direct a client when a domain boundary is crossed. This is similar to a HTTP redirect. LDAP client libraries may or may not chase referrals by default. This directive explicitly configures the referral chasing in the underlying SDK.

LDAPReferrals takes the following values:

"on"

When set to "on", the underlying SDK's referral chasing state is enabled, LDAPReferralHopLimit is used to override the SDK's hop limit, and an LDAP rebind callback is registered.

"off"

When set to "off", the underlying SDK's referral chasing state is disabled completely.

"default"

When set to "default", the underlying SDK's referral chasing state is not changed, LDAPReferralHopLimit is not used to overide the SDK's hop limit, and no LDAP rebind callback is registered.

The directive LDAPReferralHopLimit works in conjunction with this directive to limit the number of referral hops to follow before terminating the LDAP query. When referral processing is enabled by a value of "On", client credentials will be provided, via a rebind callback, for any LDAP server requiring them.

LDAPRetries Directive

Description: | Configures the number of LDAP server retries.
Syntax: | LDAPRetries number-of-retries
Default: | LDAPRetries 3
Context: | server config
Status: | Extension
Module: | mod_ldap

The server will retry failed LDAP requests up to LDAPRetries times. Setting this directive to 0 disables retries.

LDAP errors such as timeouts and refused connections are retryable.

LDAPRetryDelay Directive

Description: | Configures the delay between LDAP server retries.
Syntax: | LDAPRetryDelay seconds
Default: | LDAPRetryDelay 0
Context: | server config
Status: | Extension
Module: | mod_ldap

If LDAPRetryDelay is set to a non-zero value, the server will delay retrying an LDAP request for the specified amount of time. Setting this directive to 0 will result in any retry to occur without delay.

LDAP errors such as timeouts and refused connections are retryable.

LDAPSharedCacheFile Directive

Description: | Sets the shared memory cache file
Syntax: | LDAPSharedCacheFile directory-path/filename
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the directory path and file name of the shared memory cache file. If not set, anonymous shared memory will be used if the platform supports it.

LDAPSharedCacheSize Directive

Description: | Size in bytes of the shared-memory cache
Syntax: | LDAPSharedCacheSize bytes
Default: | LDAPSharedCacheSize 500000
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the number of bytes to allocate for the shared memory cache. The default is 500kb. If set to 0, shared memory caching will not be used and every HTTPD process will create its own cache.

LDAPTimeout Directive

Description: | Specifies the timeout for LDAP search and bind operations, in seconds
Syntax: | LDAPTimeout seconds
Default: | LDAPTimeout 60
Context: | server config
Status: | Extension
Module: | mod_ldap
Compatibility: | Apache HTTP Server 2.3.5 and later

This directive configures the timeout for bind and search operations, as well as the LDAP_OPT_TIMEOUT option in the underlying LDAP client library, when available.

If the timeout expires, httpd will retry in case an existing connection has been silently dropped by a firewall. However, performance will be much better if the firewall is configured to send TCP RST packets instead of silently dropping packets.

Timeouts for ldap compare operations requires an SDK with LDAP_OPT_TIMEOUT, such as OpenLDAP >= 2.4.4.

LDAPTrustedClientCert Directive

Description: | Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates.
Syntax: | LDAPTrustedClientCert type directory-path/filename/nickname [password]
Context: | directory, .htaccess
Status: | Extension
Module: | mod_ldap

It specifies the directory path, file name or nickname of a per connection client certificate used when establishing an SSL or TLS connection to an LDAP server. Different locations or directories may have their own independent client certificate settings. Some LDAP toolkits (notably Novell) do not support per connection client certificates, and will throw an error on LDAP server connection if you try to use this directive (Use the LDAPTrustedGlobalCert directive instead for Novell client certificates - See the SSL/TLS certificate guide above for details). The type specifies the kind of certificate parameter being set, depending on the LDAP toolkit being used. Supported types are:

  • CA_DER - binary DER encoded CA certificate
  • CA_BASE64 - PEM encoded CA certificate
  • CERT_DER - binary DER encoded client certificate
  • CERT_BASE64 - PEM encoded client certificate
  • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
  • KEY_DER - binary DER encoded private key
  • KEY_BASE64 - PEM encoded private key

LDAPTrustedGlobalCert Directive

Description: | Sets the file or database containing global trusted Certificate Authority or global client certificates
Syntax: | LDAPTrustedGlobalCert type directory-path/filename [password]
Context: | server config
Status: | Extension
Module: | mod_ldap

It specifies the directory path and file name of the trusted CA certificates and/or system wide client certificates mod_ldap should use when establishing an SSL or TLS connection to an LDAP server. Note that all certificate information specified using this directive is applied globally to the entire server installation. Some LDAP toolkits (notably Novell) require all client certificates to be set globally using this directive. Most other toolkits require clients certificates to be set per Directory or per Location using LDAPTrustedClientCert. If you get this wrong, an error may be logged when an attempt is made to contact the LDAP server, or the connection may silently fail (See the SSL/TLS certificate guide above for details). The type specifies the kind of certificate parameter being set, depending on the LDAP toolkit being used. Supported types are:

  • CA_DER - binary DER encoded CA certificate
  • CA_BASE64 - PEM encoded CA certificate
  • CA_CERT7_DB - Netscape cert7.db CA certificate database file
  • CA_SECMOD - Netscape secmod database file
  • CERT_DER - binary DER encoded client certificate
  • CERT_BASE64 - PEM encoded client certificate
  • CERT_KEY3_DB - Netscape key3.db client certificate database file
  • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
  • CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)
  • KEY_DER - binary DER encoded private key
  • KEY_BASE64 - PEM encoded private key
  • KEY_PFX - PKCS#12 encoded private key (Novell SDK)

LDAPTrustedMode Directive

Description: | Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
Syntax: | LDAPTrustedMode type
Context: | server config, virtual host
Status: | Extension
Module: | mod_ldap

The following modes are supported:

  • NONE - no encryption
  • SSL - ldaps:// encryption on default port 636
  • TLS - STARTTLS encryption on default port 389

Not all LDAP toolkits support all the above modes. An error message will be logged at runtime if a mode is not supported, and the connection to the LDAP server will fail.

If an ldaps:// URL is specified, the mode becomes SSL and the setting of LDAPTrustedMode is ignored.

LDAPVerifyServerCert Directive

Description: | Force server certificate verification
Syntax: | LDAPVerifyServerCert On|Off
Default: | LDAPVerifyServerCert On
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies whether to force the verification of a server certificate when establishing an SSL connection to the LDAP server.


mod_log_config - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_log_config

Açıklama: | Sunucuya yapılan isteklerin günlük kayıtlarının tutulması
Durum: | Temel
Modül Betimleyici: | log_config_module
Kaynak Dosyası: | mod_log_config.c

Özet

Bu modül istemci isteklerinin esnek şekilde günlüklenmesi ile ilgilidir. Günlükler kişiselleştirilebilir biçemdedir ve doğrudan bir dosyaya yazılabileceği gibi boru üzerinden harici bir sürece de yazılabilir. İsteğin özelliklerine bağlı olarak bazı isteklerin günlüklere kaydedilmesi veya kaydedilmemesi mümkün kılınmıştır.

Bu modül üç yönerge içermektedir: Bir günlük dosyası oluşturmak için TransferLog, günlük biçemini kişiselleştirmek için LogFormat ve tek başına bir günlük dosyasını hem tanımlayıp hem de biçemleyen CustomLog yönergesi. Her isteğin çok sayıda dosyaya günlüklenmesini sağlamak için yapılandırma dosyasında her sunucu için birden fazla TransferLog ve CustomLog yönergesi belirtilebilir.

Ayrıca bakınız:

  • Apache Günlük Dosyaları

Günlük Girdilerinin Kişiselleştirilmesi

LogFormat ve CustomLog yönergelerinin biçem argümanı bir dizgedir. Bu dizge her isteği günlük dosyasına günlüklemek için kullanılır. Doğrudan günlük dosyalarına kopyalanmak üzere dizgesel sabitler içerebileceği gibi satırsonu ve sekme karakterleri olarak C tarzı "\n" ve "\t" denetim karakterlerini de içerebilir. Dizgesel sabit olarak kullanılan tırnak ve tersbölü imlerinin tersbölü ile öncelenmesi gerekir.

İstek özellikleri biçem dizgesine “%” imli belirteçler yerleştirilerek günlüklenir. Bu belirteçler ve anlamları:

Belirteç | Açıklama
%% Yüzde imi.
%a | Uzak IP adresi ve isteğin portu (mod_remoteip modülüne bakın).
%{c}a | bağlantının emsal IP adresi and portu (mod_remoteip modülüne bakın).
%A | Yerel IP adresi.
%B | HTTP başlıkları hariç, yanıtın bayt cinsinden uzunluğu.
%b | HTTP başlıkları hariç, yanıtın bayt cinsinden uzunluğu. OGB biçeminde hiç bayt gönderilmemişse günlüğe '-' yerine '0' çıktılanır.
%{DEĞİŞKEN}C | İstek içinde sunucuya gönderilen DEĞİŞKEN çerezinin içeriği. Sadece 0 sürümlü çerezler tam olarak desteklenir.
%D | Mikrosaniye cinsinden isteği sunmak için harcanan zaman.
%{DEĞİŞKEN}e | DEĞİŞKEN ortam değişkeninin içeriği.
%f | Dosya ismi.
%h | Uzak konak ismi. HostnameLookups yönergesine öntanımlı olan Off değeri atanmışsa, IP adresi günlüğe kaydedilir. Bir kaç konak için konak ismi de günlüğe kaydoluyorsa muhtemelen onların isimlerini içeren erişim denetim yönergelerine sahipsinizdir. Bak: Require host.
%H | İstek Protokolü.
%{DEĞİŞKEN}i | İstekle birlikte sunucuya gönderilen DEĞİŞKEN: başlık satır(lar)ının içeriği. Diğer modüllerde (örn. mod_headers) yapılan değişikliklerden etkilenir. Modüllerin çoğu bunu değiştirdiğinde önceki istek başlık isminin ne olduğuyla ilgileniyorsanız, başlığı bir ortam değişkenine kaydetmek için mod_setenvif modülünü kullanın ve yukarıda açıklandığı gibi bu değeri %{DEĞİŞKEN}e ile günlüğe kaydedin.
%k | Bu bağlantıda işlenen isteklerin sayısı; yani örneğin, '1' değeri bağlantı kurulduktan sonraki ilk kalıcı bağlantıyı, '2', ikinci bağlantıyı, ..., vb. gösterir; KeepAlive kullanılmışsa değer anlamlıdır; aksi takdirde değer daima 0’dır.
%l | Uzak kullanıcı kimliği (sağlanmışsa, identd üzerinden). mod_ident modülü mevcut ve IdentityCheck yönergesine değer olarak On atanmış olmadıkça bu belirteç için günlüğe tire imi yazılır.
%L | Hata günlüğündeki istek günlük kimliği (veya bu istek için hata günlüğüne hiçbir şey kaydedilmemise '-'). Bu hataya neyin sebep olduğunu öğrenmek için ilgili hata günlüğü satırına bakın.
%m | İstek yöntemi.
%{DEĞİŞKEN}n | Diğer modüldeki DEĞİŞKEN bilgisinin içeriği.
%{DEĞİŞKEN}o | Yanıttaki DEĞİŞKEN: başlık satır(lar)ının içeriği.
%p | Sunucunun isteği sunduğu meşru port.
%{biçem}p | Sunucunun veya istemcinin gerçek portu veya sunucunun isteği sunduğu meşru port. Geçerli biçemler: canonical, local ve remote (anlamları sırasıyla: meşru, yerel ve uzak).
%P | İsteği sunan çocuk sürecin süreç kimliği.
%{biçem}P | İsteği sunan çocuk sürecin süreç kimliği (pid) veya evre kimliği (tid). Geçerli biçemler: pid, tid, hextid. hextid için APR 1.2.0 veya üstü gerekir.
%q | Sorgu dizgesi (bir sorgu dizgesi mevcutsa önüne bir ? eklenir yoksa hiçbir şey eklenmez).
%r | İsteğin ilk satırı.
%s | Durum. Dahili olarak yönlendirilmiş istekler için isteğin özgün durumudur. İsteğin son durumu için %>s kullanınız.
%t | [18/Sep/2011:19:18:28 -0400] biçeminde isteğin alındığı tarih ve saat. Sondaki sayı zaman diliminin GMT'ye uzaklığıdır.
%{biçem}t İsteğin alındığı tarih ve saat; biçem uzatılmış strftime(3) biçeminde belirtilmelidir (genelde yerelleştirme amaçlı). begin: (öntanımlı) ile başlayan biçemlerde süre isteğin başlangıcına göredir. end: ile başlayan biçemlerde ise süre isteğin işlenmesinin bi,tmesine yakın, günlük girdisinin yazılmaya başladığı ana göredir. strftime(3) tarafından desteklenen biçemlere ek olarak aşağıdaki biçem dizgecikleri de desteklenmektedir:
sec | Mutlak zaman başlangıcından (epoch) beri geçen saniye sayısı
msec | Mutlak zaman başlangıcından beri geçen milisaniye sayısı
usec | Mutlak zaman başlangıcından beri geçen mikrosaniye sayısı
msec_frac | milisaniyelik kesir
usec_frac | mikrosaniyelik kesir
Bu dizgecikler, aynı biçem dizgesi içinde bir diğeriyle birlikte veya strftime(3) biçemlemesiyle birlikte yer alamazlar fakat çok sayıda %{biçem}t kullanılabilir.
%T | Saniye cinsinden, isteği sunmak için harcanan zaman.
%{BİRİM}T | BİRİM ile belirtilen zaman birimi cinsinden, isteği sunmak için harcanan zaman. Geçerli birimler: milisaniye için ms, mikrosaniye için us, saniye için s. s kullanımı birimsiz %T ile aynı sonucu verir; us kullanımı %D ile aynı sonucu verir. Birimli %T kullanımı 2.4.13 ve sonrasında geçerlidir.
%u | Uzak kullanıcı (kimlik doğrulaması istenmişse vardır; durum kodu (%s) 401 ise yanlış olabilir).
%U | Herhangi bir sorgu dizgesi içermeksizin istenen URL yolu.
%v | İsteği sunan sunucunun meşru sunucu ismi (ServerName).
%V | UseCanonicalName ayarı ile ilgili sunucu ismi.
%X Yanıt tamamlandığında bağlantı durumu:
X = | Yanıt tamamlanmadan bağlantı koptu.
+ = | Yanıt gönderildikten sonra bağlantı canlı kalabilir.
- = | Yanıt gönderildikten sonra bağlantı kapatılacak.
%I | İstek ve başlıklar dahil alınan bayt sayısı. Sıfır olamaz. Bunu kullanmak için mod_logio etkin olmalıdır.
%O | Başlıklar dahil gönderilen bayt sayısı. Bir yanıtın gönderilmesinden önce istekten vazgeçilmesi gibi nadir durumlarda sıfır olabilir. Bunu kullanmak için mod_logio etkin olmalıdır.
%S | Aktarılan bayt sayısı (alınan ve gönderilen), istekler ve başlıklar dahil; sıfır olamaz. %I ve %O'nun birleşimidir. Bunu kullanmak için mod_logio etkinleştirilmelidir.
%{ALANADI}^ti | Sunucuya gönderilen istekteki ALANADI: Trailer satır(lar)ının içeriği.
%{VARNAME}^to | Sunucudan gönderilen yanıttaki ALANADI: Trailer satır(lar)ının içeriği.

Değiştiriciler

Belli öğelerin sadece belli durum kodlarıyla ilgili yanıtlarla basılabilmesi için bu durum kodları % iminden hemen sonra virgüllerle ayrılmış olarak yazılabilir. Olumsuzlama belirtmek için durum kodu listesinin önüne bir "!" konabilir.

Biçem Dizgesi | Anlamı
%400,501{User-agent}i | Sadece 400 ve 501 hatalarında User-agent günlüğe kaydedilir. Diğer durum kodları için günlüğe "-" yazılır.
%!200,304,302{Referer}i | 200,304,302 durum kodlarından biriyle dönmeyen tüm istekler için Referer başlığı durum koduyla birlikte günlüğe kaydedilir. Aksi takdirde günlüğe "-" yazılır.

İsteğin dahili olarak yönlendirilmesinde özgün durumunun mu yoksa son durumunun mu hesaba katılacağı "<" ve ">" değiştiricileri ile belirtilebilir. Öntanımlı olarak %s, %U, %T, %D, ve %r belirteçleri isteğin özgün durumuna bakarken diğerleri son durumuna bakarlar. Bu bakımdan örneğin, %>s belirteci, özgün istekteki kimliği doğrulanmış kullanıcının, dahili olarak kimlik doğrulaması gerekmeyen bir özkaynağa yönlendirilmesi halinde isteğin son durumunu kaydetmekte kullanılabilir.

Bazı Bilgiler

Güvenlik nedeniyle, 2.0.46 sürümünden itibaren %r, %i ve %o belirteçlerinde basılamayan karakterler ve diğer özel karakterler \xhh dizilimleri biçeminde öncelenmektedir. Burada hh yerine karakter numarasının onaltılık gösterimi yazılır. Bir tersbölü ile öncelenmesi gereken " ve \ ile \n, \t gibi C tarzı gösterimler bu kuralın dışındadır. 2.0.46 sürümünün öncesinde bu dizgeler öncelenmezdi ve ham günlük dosyalarıyla çalışırken dikkatli olmak gerekirdi.

2.0 sürümünden beri 1.3 sürümünün aksine %b ve %B biçem belirteçleri, istemciye gönderilen bayt sayısını değil, HTTP yanıtının bayt sayısını ifade ederdi (bu yanıt, örneğin, SSL kullanıldığında veya bağlantı koptuğunda farklı uzunlukta olur). Artık, ağa gönderilen gerçek bayt sayısını günlüğe kaydetmek için mod_logio modülü tarafından sağlanan %O biçem belirteci kullanılmaktadır.

Ek bilgi: mod_cache standat bir eylemci olarak değil hızlı bir eylemci olarak gerçeklenmiştir. Bu nedenle, içerik arabelleklemesi sözkonusu olduğunda %R biçem dizgesi herhangi bir eylemci bilgisi döndürmeyecektir.

Örnekler

Genelde herkesçe kullanılan günlük kaydı biçemleme dizgelerinden bazıları:

Ortak Günlük Biçemi (OGB)
"%h %l %u %t \"%r\" %>s %b"
Sanal Konaklı Ortak Günlük Biçemi
"%v %h %l %u %t \"%r\" %>s %b"
NCSA uzun/birleşik günlük biçemi
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Referer başlığını içeren günlük biçemi
"%{Referer}i -> %U"
User-agent başlığını içeren günlük biçemi
"%{User-agent}i"

msec_frac gibi ek biçem dizgeciklerini kullanan bir zaman biçemi belirtmek isterseniz %{format}t biçem dizgesini defalarca kullanabilirsiniz:

Milisaniyeleri de içeren bir zaman damgası
"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"

Güvenlik Kaygıları

Günlük dosyarının kaydedildiği dizine sunucuyu başlatan kullanıcı dışında diğer kullanıcılar tarafından yazılabiliyor olması halinde güvenliğinizden nasıl feragat etmiş olacağınız güvenlik ipuçları belgesinde açıklanmıştır.

BufferedLogs Yönergesi

Açıklama: | Günlük girdilerini diske yazmadan önce bellekte tamponlar
Sözdizimi: | BufferedLogs On|Off
Öntanımlı: | BufferedLogs Off
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_log_config
Uyumluluk: | 2.0.41 ve sonrasında mevcuttur.

BufferedLogs yönergesi, mod_log_config modülünün çeşitli günlük girdilerini her isteğin hemen ardından tek tek değil, bir bütün halinde diske yazılmak üzere bellekte saklanmasını sağlar. Bu, bazı sistemlerde daha verimli disk erişimi, dolayısıyla daha yüksek başarım sağlayabilir. Sadece sunucu geneli için belirtilebilir, sanal konaklar için ayrı ayrı yapılandırılamaz.

Bir çökme günlük verisi kaybına sebep olacağından bu yönerge dikkatli kullanılmalıdır.

CustomLog Yönergesi

Açıklama: | Günlük dosyasın ismini ve girdi biçemini belirler.
Sözdizimi: | CustomLog dosya|borulu-süreç biçem|takma-ad [env=[!]ortam-değişkeni]| expr=ifade]
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_log_config

CustomLog yönergesi istekleri günlüğe kaydetmek için kullanılır. Yönerge ile bir günlük biçemi belirtilebilir ve günlük kaydı isteğin özelliklerine bağlı olarak ortam değişkenleri vasıtasıyla şarta bağlı kılınabilir.

İlk argümanda günlüğün yazılacağı yer belirtilir. İki tür yer belirtilebilir:

dosya
ServerRoot yönergesinin değerine göreli bir dosya ismi.
borulu-süreç
"|" boru karakteri ile öncelenmiş olarak günlük bilgisini standart girdisinden kabul edecek sürecin ismi (veya komut satırı) Daha fazla bilgi için borulu günlüklere bakınız.

Güvenlik:

Bir borulu süreç kullanılmışsa, süreç httpd’yi başlatan kullanıcı tarafından başlatılacaktır. Sunucu root tarafından başlatılıyorsa bu root olacaktır; bu bakımdan günlük kaydını alacak programın güvenilir olması önemlidir.

Bilginize

Dosya yolunu belirtirken tersbölü çizgisi kullanılan Unix dışı platformlarda bile yapılandırma dosyasında bu amaçla normal bölü çizgilerini kullanmaya özen gösterilmelidir.

İkinci argümanda günlüğe ne yazılacağı belirtilir. Ya evvelce LogFormat yönergesi ile tanımlanmış bir takma-ad ya da içeriği Günlük Girdilerinin Kişiselleştirilmesi bölümünde açıklanmış bir biçem dizgesi olabilir.

Örneğin, aşağıdaki iki yönerge kümesi aynı etkiye sahiptir:

# Biçem dizgesi yerine takma ad içeren CustomLog
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog "logs/access_log" common

# Biçem dizgesinin kendisini içeren CustomLog
CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"

Üçüncü argüman isteğe bağlı olup,belli bir isteğin günlüğe kaydedilip kaydedilmeyeceğini belirler. Koşul, sunucu ortamında belli bir değişkenin varlığı veya yokluğu olabilir (bir 'env=!isim' durumu). İstenirse koşul keyfi bir mantıksal ifade olarak da belirtilebilir. Eğer koşul sağlanmazsa istek günlüğe kaydedilmez. İfadede bulunan HTTP başlıklarına başvurular bu başlık isimlerinin Vary başlığına eklenmesine sebep olmaz.

Ortam değişkenleri mod_setenvif ve/veya mod_rewrite modülleri kullanılarak her istek için ayrı ayrı atanabilir. Örneğin, GIF biçemli resimler için yapılan istekleri ana günlük dosyasına değil de başka bir dosyaya kaydetmek isterseniz:

SetEnvIf Request_URI \.gif$ gif-image
CustomLog "gif-requests.log" common env=gif-image
CustomLog "nongif-requests.log" common env=!gif-image

Veya eski RefererIgnore yönergesinin davranışını taklit etmek isterseniz:

SetEnvIf Referer example\.com localreferer
CustomLog "referer.log" referer env=!localreferer

GlobalLog Yönergesi

Açıklama: | Günlük dosyasının ismini ve biçemini belirler
Sözdizimi: | GlobalLog dosya|boru|sağlayıcı biçem|takma_ad [env=[!]ortam_değişkeni| expr=ifade]
Bağlam: | sunucu geneli
Durum: | Temel
Modül: | mod_log_config
Uyumluluk: | Apache HTTP Sunucusunun 2.4.19 ve sonraki sürümlerinde kullanılabilir.

GlobalLog yönergesi ana sunucu yapılandırması ve tüm tanımlı sanal konaklarca paylaşılan bir günlük tanımlar.

GlobalLog yönergesi aşağıdaki farklar dışında CustomLog yönergesine eşdeğerdir:

  • GlobalLog sanal konak bağlamında belirtilirse geçersizdir.
  • Sanal konaklar küresel bağlamda belirtilmiş bir CustomLog yönergesinin tersine GlobalLog yönergesini kendi CustomLog yönergesiymiş gibi kullanır.

LogFormat Yönergesi

Açıklama: | Bir günlük dosyasında kullanılmak üzere girdi biçemi tanımlar.
Sözdizimi: | LogFormat biçem|takma-ad [takma-ad]
Öntanımlı: | LogFormat "%h %l %u %t \"%r\" %>s %b"
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_log_config

Bu yönerge erişim günlüğü dosyasının girdi biçemini belirler.

LogFormat yönergesi iki şekilde kullanılabilir. Tek argüman belirtilebilen ilkinde daha sonra TransferLog yönergelerinde belirtilen günlüklerde kullanılmak üzere günlük biçemini belirler. Bu günlük biçemi yukarıda açıklanan biçem belirteçlerinden oluşur. Bu tek argüman yerine aşağıda açıklandığı gibi önceki bir LogFormat yönergesinde tanımlanmış bir günlük biçemine atıf yapan bir takma-ad da belirtilebilir.

LogFormat yönergesinin ikinci kullanım şeklinde biçem bir takma-ad için tanımlanır. Bu takma ad daha sonraki LogFormat veya CustomLog yönergelerinde aynı biçem dizgesini uzun uzadıya yazmamak için takma-ad olarak kullanılır. Bir LogFormat yönergesi bir takma ad tanımlamaktan başka bir şey yapmaz; yani, yaptığı iş sadece bir takma ad tanımlamaktan ibarettir, biçemi uygulamaz veya biçemi öntanımlı hale getirmez. Bu bakımdan sonraki TransferLog yönergelerini de etkilemeyecektir. Ayrıca, LogFormat yönergesi bir takma ada başka bir takma ad tanımlamakta da kullanılamaz. Bir takma adın yüzde imi (%) içeremeyeceğine de dikkat ediniz.

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

TransferLog Yönergesi

Açıklama: | Bir günlük dosyasının yerini belirtir.
Sözdizimi: | TransferLog dosya|borulu-süreç [takma-ad]
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_log_config

Bir günlük biçemi tanımlanmasını ve şarta bağlı günlük kaydını mümkün kılmaması haricinde CustomLog yönergesi gibidir. Günlük biçemi yerine kendinden önce yer alan bir LogFormat yönergesinde tanımlanan bir takma ad kullanılır. Açıkça bir günlük biçemi takma adı belirtilmedikçe Ortak Günlük Biçemi öntanımlıdır.

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog "logs/access_log"

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_log_debug - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_log_debug

Description: | Additional configurable debug logging
Status: | Experimental
Module Identifier: | log_debug_module
Source File: | mod_log_debug.c
Compatibility: | Available in Apache 2.3.14 and later

Examples

  1. Log message after request to /foo/* is processed:
    <Location "/foo/">
  LogMessage "/foo/ has been requested"
</Location>
  2. Log message if request to /foo/* is processed in a sub-request:
    <Location "/foo/">
  LogMessage "subrequest to /foo/" hook=type_checker expr=%{IS_SUBREQ}
</Location>
    The default log_transaction hook is not executed for sub-requests, therefore we have to use a different hook.
  3. Log message if an IPv6 client causes a request timeout:
    LogMessage "IPv6 timeout from %{REMOTE_ADDR}" "expr=-T %{IPV6} && %{REQUEST_STATUS} = 408"
    Note the placing of the double quotes for the expr= argument.
  4. Log the value of the "X-Foo" request environment variable in each stage of the request:
    <Location "/">
  LogMessage "%{reqenv:X-Foo}" hook=all
</Location>
    Together with microsecond time stamps in the error log, hook=all also lets you determine the times spent in the different parts of the request processing.

LogMessage Directive

Description: | Log user-defined message to error log
Syntax: | LogMessage message [hook=hook] [expr=expression]
Default: | Unset
Context: | directory
Status: | Experimental
Module: | mod_log_debug

This directive causes a user defined message to be logged to the error log. The message can use variables and functions from the ap_expr syntax. References to HTTP headers will not cause header names to be added to the Vary header. The messages are logged at loglevel info.

The hook specifies before which phase of request processing the message will be logged. The following hooks are supported:

Name
translate_name
type_checker
quick_handler
map_to_storage
check_access
check_access_ex
insert_filter
check_authn
check_authz
fixups
handler
log_transaction

The default is log_transaction. The special value all is also supported, causing a message to be logged at each phase. Not all hooks are executed for every request.

The optional expression allows to restrict the message if a condition is met. The details of the expression syntax are described in the ap_expr documentation. References to HTTP headers will not cause the header names to be added to the Vary header.


mod_log_forensic - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_log_forensic

Açıklama: | Sunucuya yapılan isteklerin adli günlük kayıtlarının tutulması
Durum: | Eklenti
Modül Betimleyici: | log_forensic_module
Kaynak Dosyası: | mod_log_forensic.c
Uyumluluk: | 2.1 sürümünden beri mod_unique_id gerekmemektedir.

Özet

Bu modül istemci isteklerinin adli günlük kayıtlarının tutulmasını sağlar. Günlük kaydı bir istek işlenmeden önce ve sonra olmak üzere iki kere yapılır, böylece günlükte her istek için iki girdi bulunur. Adli günlükleyici çok sıkı kurallara tabidir, yani:

  • Biçem sabittir. Günlük kayıt biçemi çalışma anında değiştirilemez.
  • Veriyi yazamadığı takdirde çocuk süreç beklemeksizin çıkar ve (CoreDumpDirectory yapılandırmasına bağlı olarak) bir core dosyası dökümler.

Dağıtımın support dizininde bulunan check_forensic betiği adli günlük dosyalarının değerlendirilmesinde yardımcı olabilir.

Ayrıca bakınız:

  • Apache Günlük Dosyaları
  • mod_log_config

Adli Günlük Biçemi

Her istek günlüğe iki defa kaydedilir. İlki, işlemin başlangıcında (yani, başlıklar alındıktan hemen sonra), ikincisi ise istek işlem gördükten sonra normal günlüklemenin yapıldığı sırada yapılır.

Her isteği betimlemek için eşsiz bir istek kimliği atanır. Bu adli kimliğin normal günlüğe de yazılması istenirse bu %{forensic-id}n biçem dizgesi ile yapılabilir. mod_unique_id kullanılıyorsa, onun ürettiği kimlik kullanılır.

İlk satır günlüğe, adli kimliği, istek satırını ve alınan tüm başlıkları boru karakterleri (|) ile ayrılmış olarak kaydeder. Aşağıda bir örneğe yer verilmiştir (hepsi bir satırdadır):

+yQtJf8CoAB4AAFNXBIEAAAAA|GET /manual/de/images/down.gif HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0 (X11; U; Linux i686; en-US; rv%3a1.6) Gecko/20040216 Firefox/0.8|Accept:image/png, etc...

Başlangıçtaki artı imi bu günlük satırının istekle ilgili ilk günlük kaydı olduğunu belirtir. İkinci satırda bunun yerini bir eksi imi alır:

-yQtJf8CoAB4AAFNXBIEAAAAA

check_forensic betiği komut satırı argümanı olarak günlük dosyasının ismini alır. Bu +/- kimlik çiftlerine bakarak tamamlanmamış istekler varsa bunlar hakkında uyarır.

Güvenlik Kaygıları

Günlük dosyarının kaydedildiği dizine sunucuyu başlatan kullanıcı dışında diğer kullanıcılar tarafından yazılabiliyor olması halinde güvenliğinizden nasıl feragat etmiş olacağınız güvenlik ipuçları belgesinde açıklanmıştır.

Günlük dosyaları, Authorization: başlıklarının (parola içerebilen) içerikleri gibi hassas veriler içerebileceğinden bunların sunucuyu başlatan kullanıcıdan başkası tarafından okunamaması sağlanmış olmalıdır.

ForensicLog Yönergesi

Açıklama: | Adli günlük için dosya ismini belirler.
Sözdizimi: | ForensicLog dosya-adı|borulu-süreç
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_log_forensic

ForensicLog yönergesi adli inceleme için sunucuya yapılan istekleri günlüğe kaydetmekte kullanılır. Her günlük girdisine, normal CustomLog yönergesinde kullanılarak istekle ilişkilendirilebilen eşsiz bir kimlik atanır. mod_log_forensic modülü, aktarım günlüğünün biçem dizgesinde %{forensic-id}n şeklinde kullanılmak üzere forensic-id adı verilen bir dizgecik oluşturur.

Günlüğün yazılacağı yeri belirleyen argüman şu iki değerden birini alabilir:

dosya-adı
ServerRoot yönergesinin değerine göreli bir dosya ismi.
borulu-süreç
"|" boru karakteri ile öncelenmiş olarak günlük bilgisini standart girdisinden kabul edecek sürecin ismi (veya komut satırı). Program adının ServerRoot yönergesinin değerine göre belirtildiği varsayılır.

Güvenlik:

Bir borulu süreç kullanılmışsa, süreç httpd’yi başlatan kullanıcı tarafından başlatılacaktır. Sunucu root tarafından başlatılıyorsa bu root olacaktır; bu bakımdan günlük kaydını alacak programın güvenilir olması veya daha az yetkili bir kullanıcıya geçiş yapması önemlidir.

Bilginize

Dosya yolunu belirtirken tersbölü çizgisi kullanılan Unix dışı platformlarda bile yapılandırma dosyasında bu amaçla normal bölü çizgilerini kullanmaya özen gösterilmelidir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_logio - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_logio

Açıklama: | Her isteğin girdi ve çıktı uzunluklarının günlüklenmesi.
Durum: | Eklenti
Modül Betimleyici: | logio_module
Kaynak Dosyası: | mod_logio.c

Özet

Bu modül her istekte alınan ve gönderilen bayt sayısının günlüklenmesini sağlar. Sayılar, istekte ve yanıtta yer alan başlıklar ve gövdeleri hesaba dahil ederek ağ üzerinde gerçekte gidip gelen bayt sayısını gösterir. Bayt sayımı, girdide SSL/TLS öncesinde ve çıktıda SSL/TLS sonrasında yapılır, böylece sayıların, şifrelemeyle herhangi bir değişikliği doğru olarak yansıtması sağlanmış olur.

Bu modül mod_log_config modülünü gerektirir.

SSL ile KeepAlive bağlantılar kullanıldığında, SSL uzlaşımının ek yükü, bağlantı üzerinden yapılan ilk isteğin bayt sayısını yansıtır. Her dizin için yeniden uzlaşım gerektiği takdirde bayt sayısı yeniden uzlaşımı tetikleyen istekle ilişkilendirilir.

Ayrıca bakınız:

  • mod_log_config
  • Apache Günlük Dosyaları

Özel Günlük Biçemleri

İsteğin belirgin özellikleri için, biçem dizgesinde yer alan % imli biçem belirteçlerinin yerine günlük dosyasında değerleri yazılır. Bu modül üç yeni biçem belirteci ekler:

Biçem Belirteci | Açıklama
%I | İstek gövdesi ve başlıklar dahil alınan bayt sayısı; sıfır olamaz.
%O | Başlıklar dahil gönderilen bayt sayısı; sıfır olamaz.
%S | Aktarılan bayt sayısı (alınan ve gönderilen), istekler ve başlıklar dahil; sıfır olamaz. %I ve %O'nun birleşimidir. Apache 2.4.7 ve sonrasında kullanılabilmektedir.
%^FB | İstek gelip yanıt başlıklarının ilk baytı yazılana kadar mikrosaniye cinsinden geçen zaman. Sadece LogIOTrackTTFB yönergesine ON atanmışsa kullanılabilir. Apache 2.4.13 ve sonrasında kullanılabilir.

Genel olarak, işlevsellik şöyle kullanılır:

Birleşik G/Ç günlükleme biçemi:
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %I %O"

LogIOTrackTTFB Yönergesi

Açıklama: | İlk baytın yazılmasına kadar geçen süreyi izler
Sözdizimi: | LogIOTrackTTFB ON|OFF
Öntanımlı: | LogIOTrackTTFB OFF
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | none
Durum: | Eklenti
Modül: | mod_logio
Uyumluluk: | Apache 2.4.13 ve sonrasında kullanılabilir

Bu yönerge isteğin okunmasından yanıt başlığının ilk baytının yazılmasına kadar geçen sürenin izlenmesini yapılandırır. Sonuçlanan değeri %^FB biçemi ile günlüğe kaydettirebilirsiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_lua - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_lua

Description: | Provides Lua hooks into various portions of the httpd request processing
Status: | Experimental
Module Identifier: | lua_module
Source File: | mod_lua.c
Compatibility: | 2.3 and later

Summary

This module allows the server to be extended with scripts written in the Lua programming language. The extension points (hooks) available with mod_lua include many of the hooks available to natively compiled Apache HTTP Server modules, such as mapping requests to files, generating dynamic responses, access control, authentication, and authorization

More information on the Lua programming language can be found at the the Lua website.

mod_lua is still in experimental state. Until it is declared stable, usage and behavior may change at any time, even between stable releases of the 2.4.x series. Be sure to check the CHANGES file before upgrading.

Warning

This module holds a great deal of power over httpd, which is both a strength and a potential security risk. It is not recommended that you use this module on a server that is shared with users you do not trust, as it can be abused to change the internal workings of httpd.

Basic Configuration

The basic module loading directive is

LoadModule lua_module modules/mod_lua.so

mod_lua provides a handler named lua-script, which can be used with a SetHandler or AddHandler directive:

<Files "*.lua">
    SetHandler lua-script
</Files>

This will cause mod_lua to handle requests for files ending in .lua by invoking that file's handle function.

For more flexibility, see LuaMapHandler.

Writing Handlers

In the Apache HTTP Server API, the handler is a specific kind of hook responsible for generating the response. Examples of modules that include a handler are mod_proxy, mod_cgi, and mod_status.

mod_lua always looks to invoke a Lua function for the handler, rather than just evaluating a script body CGI style. A handler function looks something like this:

example.lua

-- example handler

require "string"

--[[
     This is the default method name for Lua handlers, see the optional
     function-name in the LuaMapHandler directive to choose a different
     entry point.
--]]
function handle(r)
    r.content_type = "text/plain"

    if r.method == 'GET' then
        r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parseargs() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    elseif r.method == 'POST' then
        r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parsebody() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    elseif r.method == 'PUT' then
-- use our own Error contents
        r:puts("Unsupported HTTP method " .. r.method)
        r.status = 405
        return apache2.OK
    else
-- use the ErrorDocument
        return 501
    end
    return apache2.OK
end

This handler function just prints out the uri or form encoded arguments to a plaintext page.

This means (and in fact encourages) that you can have multiple handlers (or hooks, or filters) in the same script.

Writing Authorization Providers

mod_authz_core provides a high-level interface to authorization that is much easier to use than using into the relevant hooks directly. The first argument to the Require directive gives the name of the responsible authorization provider. For any Require line, mod_authz_core will call the authorization provider of the given name, passing the rest of the line as parameters. The provider will then check authorization and pass the result as return value.

The authz provider is normally called before authentication. If it needs to know the authenticated user name (or if the user will be authenticated at all), the provider must return apache2.AUTHZ_DENIED_NO_USER. This will cause authentication to proceed and the authz provider to be called a second time.

The following authz provider function takes two arguments, one ip address and one user name. It will allow access from the given ip address without authentication, or if the authenticated user matches the second argument:

authz_provider.lua

require 'apache2'

function authz_check_foo(r, ip, user)
    if r.useragent_ip == ip then
        return apache2.AUTHZ_GRANTED
    elseif r.user == nil then
        return apache2.AUTHZ_DENIED_NO_USER
    elseif r.user == user then
        return apache2.AUTHZ_GRANTED
    else
        return apache2.AUTHZ_DENIED
    end
end

The following configuration registers this function as provider foo and configures it for URL /:

LuaAuthzProvider foo authz_provider.lua authz_check_foo
<Location "/">
  Require foo 10.1.2.3 john_doe
</Location>

Writing Hooks

Hook functions are how modules (and Lua scripts) participate in the processing of requests. Each type of hook exposed by the server exists for a specific purpose, such as mapping requests to the file system, performing access control, or setting mime types:

Hook phase | mod_lua directive | Description
Quick handler | LuaQuickHandler | This is the first hook that will be called after a request has been mapped to a host or virtual host
Translate name | LuaHookTranslateName | This phase translates the requested URI into a filename on the system. Modules such as mod_alias and mod_rewrite operate in this phase.
Map to storage | LuaHookMapToStorage | This phase maps files to their physical, cached or external/proxied storage. It can be used by proxy or caching modules
Check Access | LuaHookAccessChecker | This phase checks whether a client has access to a resource. This phase is run before the user is authenticated, so beware.
Check User ID | LuaHookCheckUserID | This phase it used to check the negotiated user ID
Check Authorization | LuaHookAuthChecker or LuaAuthzProvider | This phase authorizes a user based on the negotiated credentials, such as user ID, client certificate etc.
Check Type | LuaHookTypeChecker | This phase checks the requested file and assigns a content type and a handler to it
Fixups | LuaHookFixups | This is the final "fix anything" phase before the content handlers are run. Any last-minute changes to the request should be made here.
Content handler | fx. .lua files or through LuaMapHandler | This is where the content is handled. Files are read, parsed, some are run, and the result is sent to the client
Logging | LuaHookLog | Once a request has been handled, it enters several logging phases, which logs the request in either the error or access log. Mod_lua is able to hook into the start of this and control logging output.

Hook functions are passed the request object as their only argument (except for LuaAuthzProvider, which also gets passed the arguments from the Require directive). They can return any value, depending on the hook, but most commonly they'll return OK, DONE, or DECLINED, which you can write in Lua as apache2.OK, apache2.DONE, or apache2.DECLINED, or else an HTTP status code.

translate_name.lua

-- example hook that rewrites the URI to a filesystem path.

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.filename = r.document_root .. "/find_me.txt"
        return apache2.OK
    end
    -- we don't care about this URL, give another module a chance
    return apache2.DECLINED
end
translate_name2.lua

--[[ example hook that rewrites one URI to another URI. It returns a
     apache2.DECLINED to give other URL mappers a chance to work on the
     substitution, including the core translate_name hook which maps based
     on the DocumentRoot.

     Note: Use the early/late flags in the directive to make it run before
           or after mod_alias.
--]]

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.uri = "/find_me.txt"
        return apache2.DECLINED
    end
    return apache2.DECLINED
end

Data Structures

request_rec

The request_rec is mapped in as a userdata. It has a metatable which lets you do useful things with it. For the most part it has the same fields as the request_rec struct, many of which are writable as well as readable. (The table fields' content can be changed, but the fields themselves cannot be set to different tables.)

Name | Lua type | Writable | Description
allowoverrides | string | no | The AllowOverride options applied to the current request.
ap_auth_type | string | no | If an authentication check was made, this is set to the type of authentication (f.x. basic)
args | string | yes | The query string arguments extracted from the request (f.x. foo=bar&name=johnsmith)
assbackwards | boolean | no | Set to true if this is an HTTP/0.9 style request (e.g. GET /foo (with no headers) )
auth_name | string | no | The realm name used for authorization (if applicable).
banner | string | no | The server banner, f.x. Apache HTTP Server/2.4.3 openssl/0.9.8c
basic_auth_pw | string | no | The basic auth password sent with this request, if any
canonical_filename | string | no | The canonical filename of the request
content_encoding | string | no | The content encoding of the current request
content_type | string | yes | The content type of the current request, as determined in the type_check phase (f.x. image/gif or text/html)
context_prefix | string | no
context_document_root | string | no
document_root | string | no | The document root of the host
err_headers_out | table | no | MIME header environment for the response, printed even on errors and persist across internal redirects
filename | string | yes | The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be changed in the translate-name or map-to-storage phases of a request to allow the default handler (or script handlers) to serve a different file than what was requested.
handler | string | yes | The name of the handler that should serve this request, f.x. lua-script if it is to be served by mod_lua. This is typically set by the AddHandler or SetHandler directives, but could also be set via mod_lua to allow another handler to serve up a specific request that would otherwise not be served by it.
headers_in | table | yes | MIME header environment from the request. This contains headers such as Host, User-Agent, Referer and so on.
headers_out | table | yes | MIME header environment for the response.
hostname | string | no | The host name, as set by the Host: header or by a full URI.
is_https | boolean | no | Whether or not this request is done via HTTPS
is_initial_req | boolean | no | Whether this request is the initial request or a sub-request
limit_req_body | number | no | The size limit of the request body for this request, or 0 if no limit.
log_id | string | no | The ID to identify request in access and error log.
method | string | no | The request method, f.x. GET or POST.
notes | table | yes | A list of notes that can be passed on from one module to another.
options | string | no | The Options directive applied to the current request.
path_info | string | no | The PATH_INFO extracted from this request.
port | number | no | The server port used by the request.
protocol | string | no | The protocol used, f.x. HTTP/1.1
proxyreq | string | yes | Denotes whether this is a proxy request or not. This value is generally set in the post_read_request/translate_name phase of a request.
range | string | no | The contents of the Range: header.
remaining | number | no | The number of bytes remaining to be read from the request body.
server_built | string | no | The time the server executable was built.
server_name | string | no | The server name for this request.
some_auth_required | boolean | no | Whether some authorization is/was required for this request.
subprocess_env | table | yes | The environment variables set for this request.
started | number | no | The time the server was (re)started, in seconds since the epoch (Jan 1st, 1970)
status | number | yes | The (current) HTTP return code for this request, f.x. 200 or 404.
the_request | string | no | The request string as sent by the client, f.x. GET /foo/bar HTTP/1.1.
unparsed_uri | string | no | The unparsed URI of the request
uri | string | yes | The URI after it has been parsed by httpd
user | string | yes | If an authentication check has been made, this is set to the name of the authenticated user.
useragent_ip | string | no | The IP of the user agent making the request

Built in functions

The request_rec object has (at least) the following methods:

r:flush()   -- flushes the output buffer.
            -- Returns true if the flush was successful, false otherwise.

while we_have_stuff_to_send do
    r:puts("Bla bla bla\n") -- print something to client
    r:flush() -- flush the buffer (send to client)
    r.usleep(500000) -- fake processing time for 0.5 sec. and repeat
end
r:addoutputfilter(name|function) -- add an output filter:

r:addoutputfilter("fooFilter") -- add the fooFilter to the output stream
r:sendfile(filename) -- sends an entire file to the client, using sendfile if supported by the current platform:

if use_sendfile_thing then
    r:sendfile("/var/www/large_file.img")
end
r:parseargs() -- returns two tables; one standard key/value table for regular GET data,
              -- and one for multi-value data (fx. foo=1&foo=2&foo=3):

local GET, GETMULTI = r:parseargs()
r:puts("Your name is: " .. GET['name'] or "Unknown")
r:parsebody([sizeLimit]) -- parse the request body as a POST and return two lua tables,
                         -- just like r:parseargs().
                         -- An optional number may be passed to specify the maximum number
                         -- of bytes to parse. Default is 8192 bytes:

local POST, POSTMULTI = r:parsebody(1024*1024)
r:puts("Your name is: " .. POST['name'] or "Unknown")
r:puts("hello", " world", "!") -- print to response body, self explanatory
r:write("a single string") -- print to response body, self explanatory
r:escape_html("<html>test</html>") -- Escapes HTML code and returns the escaped result
r:base64_encode(string) -- Encodes a string using the Base64 encoding standard:

local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=
r:base64_decode(string) -- Decodes a Base64-encoded string:

local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'
r:md5(string) -- Calculates and returns the MD5 digest of a string (binary safe):

local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339
r:sha1(string) -- Calculates and returns the SHA1 digest of a string (binary safe):

local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19
r:escape(string) -- URL-Escapes a string:

local url = "http://foo.bar/1 2 3 & 4 + 5"
local escaped = r:escape(url) -- returns 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'
r:unescape(string) -- Unescapes an URL-escaped string:

local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
local unescaped = r:unescape(url) -- returns 'http://foo.bar/1 2 3 & 4 + 5'
r:construct_url(string) -- Constructs an URL from an URI

local url = r:construct_url(r.uri)
r.mpm_query(number) -- Queries the server for MPM information using ap_mpm_query:

local mpm = r.mpm_query(14)
if mpm == 1 then
    r:puts("This server uses the Event MPM")
end
r:expr(string) -- Evaluates an expr string.

if r:expr("%{HTTP_HOST} =~ /^www/") then
    r:puts("This host name starts with www")
end
r:scoreboard_process(a) -- Queries the server for information about the process at position a:

local process = r:scoreboard_process(1)
r:puts("Server 1 has PID " .. process.pid)
r:scoreboard_worker(a, b) -- Queries for information about the worker thread, b, in process a:

local thread = r:scoreboard_worker(1, 1)
r:puts("Server 1's thread 1 has thread ID " .. thread.tid .. " and is in " .. thread.status .. " status")
r:clock() -- Returns the current time with microsecond precision
r:requestbody(filename) -- Reads and returns the request body of a request.
                -- If 'filename' is specified, it instead saves the
                -- contents to that file:

local input = r:requestbody()
r:puts("You sent the following request body to me:\n")
r:puts(input)
r:add_input_filter(filter_name) -- Adds 'filter_name' as an input filter
r.module_info(module_name) -- Queries the server for information about a module

local mod = r.module_info("mod_lua.c")
if mod then
    for k, v in pairs(mod.commands) do
       r:puts( ("%s: %s\n"):format(k,v)) -- print out all directives accepted by this module
    end
end
r:loaded_modules() -- Returns a list of modules loaded by httpd:

for k, module in pairs(r:loaded_modules()) do
    r:puts("I have loaded module " .. module .. "\n")
end
r:runtime_dir_relative(filename) -- Compute the name of a run-time file (e.g., shared memory "file")
                         -- relative to the appropriate run-time directory.
r:server_info() -- Returns a table containing server information, such as
                -- the name of the httpd executable file, mpm used etc.
r:set_document_root(file_path) -- Sets the document root for the request to file_path
r:set_context_info(prefix, docroot) -- Sets the context prefix and context document root for a request
r:os_escape_path(file_path) -- Converts an OS path to a URL in an OS dependent way
r:escape_logitem(string) -- Escapes a string for logging
r.strcmp_match(string, pattern) -- Checks if 'string' matches 'pattern' using strcmp_match (globs).
                        -- fx. whether 'www.example.com' matches '*.example.com':

local match = r.strcmp_match("foobar.com", "foo*.com")
if match then
    r:puts("foobar.com matches foo*.com")
end
r:set_keepalive() -- Sets the keepalive status for a request. Returns true if possible, false otherwise.
r:make_etag() -- Constructs and returns the etag for the current request.
r:send_interim_response(clear) -- Sends an interim (1xx) response to the client.
                       -- if 'clear' is true, available headers will be sent and cleared.
r:custom_response(status_code, string) -- Construct and set a custom response for a given status code.
                               -- This works much like the ErrorDocument directive:

r:custom_response(404, "Baleted!")
r.exists_config_define(string) -- Checks whether a configuration definition exists or not:

if r.exists_config_define("FOO") then
    r:puts("httpd was probably run with -DFOO, or it was defined in the configuration")
end
r:state_query(string) -- Queries the server for state information
r:stat(filename [,wanted]) -- Runs stat() on a file, and returns a table with file information:

local info = r:stat("/var/www/foo.txt")
if info then
    r:puts("This file exists and was last modified at: " .. info.modified)
end
r:regex(string, pattern [,flags]) -- Runs a regular expression match on a string, returning captures if matched:

local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
if matches then
    r:puts("The regex matched, and the last word captured ($2) was: " .. matches[2])
end

-- Example ignoring case sensitivity:
local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)

-- Flags can be a bitwise combination of:
-- 0x01: Ignore case
-- 0x02: Multiline search
r.usleep(number_of_microseconds) -- Puts the script to sleep for a given number of microseconds.
r:dbacquire(dbType[, dbParams]) -- Acquires a connection to a database and returns a database class.
                        -- See 'Database connectivity' for details.
r:ivm_set("key", value) -- Set an Inter-VM variable to hold a specific value.
                        -- These values persist even though the VM is gone or not being used,
                        -- and so should only be used if MaxConnectionsPerChild is > 0
                        -- Values can be numbers, strings and booleans, and are stored on a
                        -- per process basis (so they won't do much good with a prefork mpm)

r:ivm_get("key")        -- Fetches a variable set by ivm_set. Returns the contents of the variable
                        -- if it exists or nil if no such variable exists.

-- An example getter/setter that saves a global variable outside the VM:
function handle(r)
    -- First VM to call this will get no value, and will have to create it
    local foo = r:ivm_get("cached_data")
    if not foo then
        foo = do_some_calcs() -- fake some return value
        r:ivm_set("cached_data", foo) -- set it globally
    end
    r:puts("Cached data is: ", foo)
end
r:htpassword(string [,algorithm [,cost]]) -- Creates a password hash from a string.
                                          -- algorithm: 0 = APMD5 (default), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
                                          -- cost: only valid with BCRYPT algorithm (default = 5).
r:mkdir(dir [,mode]) -- Creates a directory and sets mode to optional mode paramter.
r:mkrdir(dir [,mode]) -- Creates directories recursive and sets mode to optional mode paramter.
r:rmdir(dir) -- Removes a directory.
r:touch(file [,mtime]) -- Sets the file modification time to current time or to optional mtime msec value.
r:get_direntries(dir) -- Returns a table with all directory entries.

function handle(r)
  local dir = r.context_document_root
  for _, f in ipairs(r:get_direntries(dir)) do
    local info = r:stat(dir .. "/" .. f)
    if info then
      local mtime = os.date(fmt, info.mtime / 1000000)
      local ftype = (info.filetype == 2) and "[dir] " or "[file]"
      r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
    end
  end
end
r.date_parse_rfc(string) -- Parses a date/time string and returns seconds since epoche.
r:getcookie(key) -- Gets a HTTP cookie
r:setcookie{
  key = [key],
  value = [value],
  expires = [expiry],
  secure = [boolean],
  httponly = [boolean],
  path = [path],
  domain = [domain]
} -- Sets a HTTP cookie, for instance:

r:setcookie{
  key = "cookie1",
  value = "HDHfa9eyffh396rt",
  expires = os.time() + 86400,
  secure = true
}
r:wsupgrade() -- Upgrades a connection to WebSockets if possible (and requested):
if r:wsupgrade() then -- if we can upgrade:
    r:wswrite("Welcome to websockets!") -- write something to the client
    r:wsclose()  -- goodbye!
end
r:wsread() -- Reads a WebSocket frame from a WebSocket upgraded connection (see above):

local line, isFinal = r:wsread() -- isFinal denotes whether this is the final frame.
                                 -- If it isn't, then more frames can be read
r:wswrite("You wrote: " .. line)
r:wswrite(line) -- Writes a frame to a WebSocket client:
r:wswrite("Hello, world!")
r:wsclose() -- Closes a WebSocket request and terminates it for httpd:

if r:wsupgrade() then
    r:wswrite("Write something: ")
    local line = r:wsread() or "nothing"
    r:wswrite("You wrote: " .. line);
    r:wswrite("Goodbye!")
    r:wsclose()
end

Logging Functions

        -- examples of logging messages

        r:trace1("This is a trace log message") -- trace1 through trace8 can be used

        r:debug("This is a debug log message")

        r:info("This is an info log message")

        r:notice("This is a notice log message")

        r:warn("This is a warn log message")

        r:err("This is an err log message")

        r:alert("This is an alert log message")

        r:crit("This is a crit log message")

        r:emerg("This is an emerg log message")

apache2 Package

A package named apache2 is available with (at least) the following contents.

apache2.OK
internal constant OK. Handlers should return this if they've handled the request.
apache2.DECLINED
internal constant DECLINED. Handlers should return this if they are not going to handle the request.
apache2.DONE
internal constant DONE.
apache2.version
Apache HTTP server version string
apache2.HTTP_MOVED_TEMPORARILY
HTTP status code
apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE
internal constants used by mod_proxy
apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER
internal constants used by mod_authz_core

(Other HTTP status codes are not yet implemented.)

Modifying contents with Lua filters

Filter functions implemented via LuaInputFilter or LuaOutputFilter are designed as three-stage non-blocking functions using coroutines to suspend and resume a function as buckets are sent down the filter chain. The core structure of such a function is:

function filter(r)
    -- Our first yield is to signal that we are ready to receive buckets.
    -- Before this yield, we can set up our environment, check for conditions,
    -- and, if we deem it necessary, decline filtering a request alltogether:
    if something_bad then
        return -- This would skip this filter.
    end
    -- Regardless of whether we have data to prepend, a yield MUST be called here.
    -- Note that only output filters can prepend data. Input filters must use the
    -- final stage to append data to the content.
    coroutine.yield([optional header to be prepended to the content])

    -- After we have yielded, buckets will be sent to us, one by one, and we can
    -- do whatever we want with them and then pass on the result.
    -- Buckets are stored in the global variable 'bucket', so we create a loop
    -- that checks if 'bucket' is not nil:
    while bucket ~= nil do
        local output = mangle(bucket) -- Do some stuff to the content
        coroutine.yield(output) -- Return our new content to the filter chain
    end

    -- Once the buckets are gone, 'bucket' is set to nil, which will exit the
    -- loop and land us here. Anything extra we want to append to the content
    -- can be done by doing a final yield here. Both input and output filters
    -- can append data to the content in this phase.
    coroutine.yield([optional footer to be appended to the content])
end

Database connectivity

Mod_lua implements a simple database feature for querying and running commands on the most popular database engines (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle) as well as mod_dbd.

The example below shows how to acquire a database handle and return information from a table:

function handle(r)
    -- Acquire a database handle
    local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
    if not err then
        -- Select some information from it
        local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
        if not err then
            local rows = results(0) -- fetch all rows synchronously
            for k, row in pairs(rows) do
                r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
            end
        else
            r:puts("Database query error: " .. err)
        end
        database:close()
    else
        r:puts("Could not connect to the database: " .. err)
    end
end

To utilize mod_dbd, specify mod_dbd as the database type, or leave the field blank:

local database = r:dbacquire("mod_dbd")

Database object and contained functions

The database object returned by dbacquire has the following methods:

Normal select and query from a database:

-- Run a statement and return the number of rows affected:
local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")

-- Run a statement and return a result set that can be used synchronously or async:
local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")

Using prepared statements (recommended):

-- Create and run a prepared statement:
local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
if not errmsg then
    local result, errmsg = statement:query(20) -- run the statement with age > 20
end

-- Fetch a prepared statement from a DBDPrepareSQL directive:
local statement, errmsg = database:prepared(r, "someTag")
if not errmsg then
    local result, errmsg = statement:select("John Doe", 123) -- inject the values "John Doe" and 123 into the statement
end

Escaping values, closing databases etc:

-- Escape a value for use in a statement:
local escaped = database:escape(r, [["'|blabla]])

-- Close a database connection and free up handles:
database:close()

-- Check whether a database connection is up and running:
local connected = database:active()

Working with result sets

The result set returned by db:select or by the prepared statement functions created through db:prepare can be used to fetch rows synchronously or asynchronously, depending on the row number specified:
result(0) fetches all rows in a synchronous manner, returning a table of rows.
result(-1) fetches the next available row in the set, asynchronously.
result(N) fetches row number N, asynchronously:

-- fetch a result set using a regular query:
local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")

local rows = result(0) -- Fetch ALL rows synchronously
local row = result(-1) -- Fetch the next available row, asynchronously
local row = result(1234) -- Fetch row number 1234, asynchronously
local row = result(-1, true) -- Fetch the next available row, using row names as key indexes.

One can construct a function that returns an iterative function to iterate over all rows in a synchronous or asynchronous way, depending on the async argument:

function rows(resultset, async)
    local a = 0
    local function getnext()
        a = a + 1
        local row = resultset(-1)
        return row and a or nil, row
    end
    if not async then
        return pairs(resultset(0))
    else
        return getnext, self
    end
end

local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
if not err then
     -- fetch rows asynchronously:
    local result, err = statement:select(20)
    if not err then
        for index, row in rows(result, true) do
            ....
        end
    end

     -- fetch rows synchronously:
    local result, err = statement:select(20)
    if not err then
        for index, row in rows(result, false) do
            ....
        end
    end
end

Closing a database connection

Database handles should be closed using database:close() when they are no longer needed. If you do not close them manually, they will eventually be garbage collected and closed by mod_lua, but you may end up having too many unused connections to the database if you leave the closing up to mod_lua. Essentially, the following two measures are the same:

-- Method 1: Manually close a handle
local database = r:dbacquire("mod_dbd")
database:close() -- All done

-- Method 2: Letting the garbage collector close it
local database = r:dbacquire("mod_dbd")
database = nil -- throw away the reference
collectgarbage() -- close the handle via GC

Precautions when working with databases

Although the standard query and run functions are freely available, it is recommended that you use prepared statements whenever possible, to both optimize performance (if your db handle lives on for a long time) and to minimize the risk of SQL injection attacks. run and query should only be used when there are no variables inserted into a statement (a static statement). When using dynamic statements, use db:prepare or db:prepared.

LuaAuthzProvider Directive

Description: | Plug an authorization provider function into mod_authz_core
Syntax: | LuaAuthzProvider provider_name /path/to/lua/script.lua function_name
Context: | server config
Status: | Experimental
Module: | mod_lua
Compatibility: | 2.4.3 and later

After a lua function has been registered as authorization provider, it can be used with the Require directive:

LuaRoot "/usr/local/apache2/lua"
LuaAuthzProvider foo authz.lua authz_check_foo
<Location "/">
  Require foo johndoe
</Location>
require "apache2"
function authz_check_foo(r, who)
    if r.user ~= who then return apache2.AUTHZ_DENIED
    return apache2.AUTHZ_GRANTED
end

LuaCodeCache Directive

Description: | Configure the compiled code cache.
Syntax: | LuaCodeCache stat|forever|never
Default: | LuaCodeCache stat
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Specify the behavior of the in-memory code cache. The default is stat, which stats the top level script (not any included ones) each time that file is needed, and reloads it if the modified time indicates it is newer than the one it has already loaded. The other values cause it to keep the file cached forever (don't stat and replace) or to never cache the file.

In general stat or forever is good for production, and stat or never for development.

Examples:

LuaCodeCache stat
LuaCodeCache forever
LuaCodeCache never

LuaHookAccessChecker Directive

Description: | Provide a hook for the access_checker phase of request processing
Syntax: | LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late]
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua
Compatibility: | The optional third argument is supported in 2.3.15 and later

Add your hook to the access_checker phase. An access checker hook function usually returns OK, DECLINED, or HTTP_FORBIDDEN.

Ordering

The optional arguments "early" or "late" control when this script runs relative to other modules.

LuaHookAuthChecker Directive

Description: | Provide a hook for the auth_checker phase of request processing
Syntax: | LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late]
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua
Compatibility: | The optional third argument is supported in 2.3.15 and later

Invoke a lua function in the auth_checker phase of processing a request. This can be used to implement arbitrary authentication and authorization checking. A very simple example:

require 'apache2'

-- fake authcheck hook
-- If request has no auth info, set the response header and
-- return a 401 to ask the browser for basic auth info.
-- If request has auth info, don't actually look at it, just
-- pretend we got userid 'foo' and validated it.
-- Then check if the userid is 'foo' and accept the request.
function authcheck_hook(r)

   -- look for auth info
   auth = r.headers_in['Authorization']
   if auth ~= nil then
     -- fake the user
     r.user = 'foo'
   end

   if r.user == nil then
      r:debug("authcheck: user is nil, returning 401")
      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
      return 401
   elseif r.user == "foo" then
      r:debug('user foo: OK')
   else
      r:debug("authcheck: user='" .. r.user .. "'")
      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
      return 401
   end
   return apache2.OK
end

Ordering

The optional arguments "early" or "late" control when this script runs relative to other modules.

LuaHookCheckUserID Directive

Description: | Provide a hook for the check_user_id phase of request processing
Syntax: | LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late]
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua
Compatibility: | The optional third argument is supported in 2.3.15 and later

...

Ordering

The optional arguments "early" or "late" control when this script runs relative to other modules.

LuaHookFixups Directive

Description: | Provide a hook for the fixups phase of a request processing
Syntax: | LuaHookFixups /path/to/lua/script.lua hook_function_name
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Just like LuaHookTranslateName, but executed at the fixups phase

LuaHookInsertFilter Directive

Description: | Provide a hook for the insert_filter phase of request processing
Syntax: | LuaHookInsertFilter /path/to/lua/script.lua hook_function_name
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Not Yet Implemented

LuaHookLog Directive

Description: | Provide a hook for the access log phase of a request processing
Syntax: | LuaHookLog /path/to/lua/script.lua log_function_name
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

This simple logging hook allows you to run a function when httpd enters the logging phase of a request. With it, you can append data to your own logs, manipulate data before the regular log is written, or prevent a log entry from being created. To prevent the usual logging from happening, simply return apache2.DONE in your logging handler, otherwise return apache2.OK to tell httpd to log as normal.

Example:

LuaHookLog "/path/to/script.lua" logger
-- /path/to/script.lua --
function logger(r)
    -- flip a coin:
    -- If 1, then we write to our own Lua log and tell httpd not to log
    -- in the main log.
    -- If 2, then we just sanitize the output a bit and tell httpd to
    -- log the sanitized bits.

    if math.random(1,2) == 1 then
        -- Log stuff ourselves and don't log in the regular log
        local f = io.open("/foo/secret.log", "a")
        if f then
            f:write("Something secret happened at " .. r.uri .. "\n")
            f:close()
        end
        return apache2.DONE -- Tell httpd not to use the regular logging functions
    else
        r.uri = r.uri:gsub("somesecretstuff", "") -- sanitize the URI
        return apache2.OK -- tell httpd to log it.
    end
end

LuaHookMapToStorage Directive

Description: | Provide a hook for the map_to_storage phase of request processing
Syntax: | LuaHookMapToStorage /path/to/lua/script.lua hook_function_name
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Like LuaHookTranslateName but executed at the map-to-storage phase of a request. Modules like mod_cache run at this phase, which makes for an interesting example on what to do here:

LuaHookMapToStorage "/path/to/lua/script.lua" check_cache
require"apache2"
cached_files = {}

function read_file(filename)
    local input = io.open(filename, "r")
    if input then
        local data = input:read("*a")
        cached_files[filename] = data
        file = cached_files[filename]
        input:close()
    end
    return cached_files[filename]
end

function check_cache(r)
    if r.filename:match("%.png$") then -- Only match PNG files
        local file = cached_files[r.filename] -- Check cache entries
        if not file then
            file = read_file(r.filename)  -- Read file into cache
        end
        if file then -- If file exists, write it out
            r.status = 200
            r:write(file)
            r:info(("Sent %s to client from cache"):format(r.filename))
            return apache2.DONE -- skip default handler for PNG files
        end
    end
    return apache2.DECLINED -- If we had nothing to do, let others serve this.
end

LuaHookTranslateName Directive

Description: | Provide a hook for the translate name phase of request processing
Syntax: | LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late]
Context: | server config, virtual host
Override: | All
Status: | Experimental
Module: | mod_lua
Compatibility: | The optional third argument is supported in 2.3.15 and later

Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of request processing. The hook function receives a single argument, the request_rec, and should return a status code, which is either an HTTP error code, or the constants defined in the apache2 module: apache2.OK, apache2.DECLINED, or apache2.DONE.

For those new to hooks, basically each hook will be invoked until one of them returns apache2.OK. If your hook doesn't want to do the translation it should just return apache2.DECLINED. If the request should stop processing, then return apache2.DONE.

Example:

# httpd.conf
LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper
-- /scripts/conf/hooks.lua --
require "apache2"
function silly_mapper(r)
    if r.uri == "/" then
        r.filename = "/var/www/home.lua"
        return apache2.OK
    else
        return apache2.DECLINED
    end
end

Context

This directive is not valid in <Directory>, <Files>, or htaccess context.

Ordering

The optional arguments "early" or "late" control when this script runs relative to other modules.

LuaHookTypeChecker Directive

Description: | Provide a hook for the type_checker phase of request processing
Syntax: | LuaHookTypeChecker /path/to/lua/script.lua hook_function_name
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

This directive provides a hook for the type_checker phase of the request processing. This phase is where requests are assigned a content type and a handler, and thus can be used to modify the type and handler based on input:

LuaHookTypeChecker "/path/to/lua/script.lua" type_checker
    function type_checker(r)
        if r.uri:match("%.to_gif$") then -- match foo.png.to_gif
            r.content_type = "image/gif" -- assign it the image/gif type
            r.handler = "gifWizard"      -- tell the gifWizard module to handle this
            r.filename = r.uri:gsub("%.to_gif$", "") -- fix the filename requested
            return apache2.OK
        end

        return apache2.DECLINED
    end

LuaInherit Directive

Description: | Controls how parent configuration sections are merged into children
Syntax: | LuaInherit none|parent-first|parent-last
Default: | LuaInherit parent-first
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua
Compatibility: | 2.4.0 and later

By default, if LuaHook* directives are used in overlapping Directory or Location configuration sections, the scripts defined in the more specific section are run after those defined in the more generic section (LuaInherit parent-first). You can reverse this order, or make the parent context not apply at all.

In previous 2.3.x releases, the default was effectively to ignore LuaHook* directives from parent configuration sections.

LuaInputFilter Directive

Description: | Provide a Lua function for content input filtering
Syntax: | LuaInputFilter filter_name /path/to/lua/script.lua function_name
Context: | server config
Status: | Experimental
Module: | mod_lua
Compatibility: | 2.4.5 and later

Provides a means of adding a Lua function as an input filter. As with output filters, input filters work as coroutines, first yielding before buffers are sent, then yielding whenever a bucket needs to be passed down the chain, and finally (optionally) yielding anything that needs to be appended to the input data. The global variable bucket holds the buckets as they are passed onto the Lua script:

LuaInputFilter myInputFilter "/www/filter.lua" input_filter
<Files "*.lua">
  SetInputFilter myInputFilter
</Files>
--[[
    Example input filter that converts all POST data to uppercase.
]]--
function input_filter(r)
    print("luaInputFilter called") -- debug print
    coroutine.yield() -- Yield and wait for buckets
    while bucket do -- For each bucket, do...
        local output = string.upper(bucket) -- Convert all POST data to uppercase
        coroutine.yield(output) -- Send converted data down the chain
    end
    -- No more buckets available.
    coroutine.yield("&filterSignature=1234") -- Append signature at the end
end

The input filter supports denying/skipping a filter if it is deemed unwanted:

function input_filter(r)
    if not good then
        return -- Simply deny filtering, passing on the original content instead
    end
    coroutine.yield() -- wait for buckets
    ... -- insert filter stuff here
end

See "Modifying contents with Lua filters" for more information.

LuaMapHandler Directive

Description: | Map a path to a lua handler
Syntax: | LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

This directive matches a uri pattern to invoke a specific handler function in a specific file. It uses PCRE regular expressions to match the uri, and supports interpolating match groups into both the file path and the function name. Be careful writing your regular expressions to avoid security issues.

Examples:

LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"

This would match uri's such as /photos/show?id=9 to the file /scripts/photos.lua and invoke the handler function handle_show on the lua vm after loading that file.

LuaMapHandler "/bingo" "/scripts/wombat.lua"

This would invoke the "handle" function, which is the default if no specific function name is provided.

LuaOutputFilter Directive

Description: | Provide a Lua function for content output filtering
Syntax: | LuaOutputFilter filter_name /path/to/lua/script.lua function_name
Context: | server config
Status: | Experimental
Module: | mod_lua
Compatibility: | 2.4.5 and later

Provides a means of adding a Lua function as an output filter. As with input filters, output filters work as coroutines, first yielding before buffers are sent, then yielding whenever a bucket needs to be passed down the chain, and finally (optionally) yielding anything that needs to be appended to the input data. The global variable bucket holds the buckets as they are passed onto the Lua script:

LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
<Files "*.lua">
  SetOutputFilter myOutputFilter
</Files>
--[[
    Example output filter that escapes all HTML entities in the output
]]--
function output_filter(r)
    coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Prepend some data to the output,
                                                          -- yield and wait for buckets.
    while bucket do -- For each bucket, do...
        local output = r:escape_html(bucket) -- Escape all output
        coroutine.yield(output) -- Send converted data down the chain
    end
    -- No more buckets available.
end

As with the input filter, the output filter supports denying/skipping a filter if it is deemed unwanted:

function output_filter(r)
    if not r.content_type:match("text/html") then
        return -- Simply deny filtering, passing on the original content instead
    end
    coroutine.yield() -- wait for buckets
    ... -- insert filter stuff here
end

Lua filters with mod_filter

When a Lua filter is used as the underlying provider via the FilterProvider directive, filtering will only work when the filter-name is identical to the provider-name.

See "Modifying contents with Lua filters" for more information.

LuaPackageCPath Directive

Description: | Add a directory to lua's package.cpath
Syntax: | LuaPackageCPath /path/to/include/?.soa
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Add a path to lua's shared library search path. Follows the same conventions as lua. This just munges the package.cpath in the lua vms.

LuaPackagePath Directive

Description: | Add a directory to lua's package.path
Syntax: | LuaPackagePath /path/to/include/?.lua
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Add a path to lua's module search path. Follows the same conventions as lua. This just munges the package.path in the lua vms.

Examples:

LuaPackagePath "/scripts/lib/?.lua"
LuaPackagePath "/scripts/lib/?/init.lua"

LuaQuickHandler Directive

Description: | Provide a hook for the quick handler of request processing
Syntax: | LuaQuickHandler /path/to/script.lua hook_function_name
Context: | server config, virtual host
Override: | All
Status: | Experimental
Module: | mod_lua

This phase is run immediately after the request has been mapped to a virtal host, and can be used to either do some request processing before the other phases kick in, or to serve a request without the need to translate, map to storage et cetera. As this phase is run before anything else, directives such as <Location> or <Directory> are void in this phase, just as URIs have not been properly parsed yet.

Context

This directive is not valid in <Directory>, <Files>, or htaccess context.

LuaRoot Directive

Description: | Specify the base path for resolving relative paths for mod_lua directives
Syntax: | LuaRoot /path/to/a/directory
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Specify the base path which will be used to evaluate all relative paths within mod_lua. If not specified they will be resolved relative to the current working directory, which may not always work well for a server.

LuaScope Directive

Description: | One of once, request, conn, thread -- default is once
Syntax: | LuaScope once|request|conn|thread|server [min] [max]
Default: | LuaScope once
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Experimental
Module: | mod_lua

Specify the life cycle scope of the Lua interpreter which will be used by handlers in this "Directory." The default is "once"

once:
use the interpreter once and throw it away.
request:
use the interpreter to handle anything based on the same file within this request, which is also request scoped.
conn:
Same as request but attached to the connection_rec
thread:
Use the interpreter for the lifetime of the thread handling the request (only available with threaded MPMs).
server:
This one is different than others because the server scope is quite long lived, and multiple threads will have the same server_rec. To accommodate this, server scoped Lua states are stored in an apr resource list. The min and max arguments specify the minimum and maximum number of Lua states to keep in the pool.

Generally speaking, the thread and server scopes execute roughly 2-3 times faster than the rest, because they don't have to spawn new Lua states on every request (especially with the event MPM, as even keepalive requests will use a new thread for each request). If you are satisfied that your scripts will not have problems reusing a state, then the thread or server scopes should be used for maximum performance. While the thread scope will provide the fastest responses, the server scope will use less memory, as states are pooled, allowing f.x. 1000 threads to share only 100 Lua states, thus using only 10% of the memory required by the thread scope.


mod_macro - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_macro

Description: | Provides macros within apache httpd runtime configuration files
Status: | Base
Module Identifier: | macro_module
Source File: | mod_macro.c

Summary

Provides macros within Apache httpd runtime configuration files, to ease the process of creating numerous similar configuration blocks. When the server starts up, the macros are expanded using the provided parameters, and the result is processed as along with the rest of the configuration file.

Usage

Macros are defined using <Macro> blocks, which contain the portion of your configuration that needs to be repeated, complete with variables for those parts that will need to be substituted.

For example, you might use a macro to define a <VirtualHost> block, in order to define multiple similar virtual hosts:

<Macro VHost $name $domain>
<VirtualHost *:80>
    ServerName $domain
    ServerAlias www.$domain

    DocumentRoot "/var/www/vhosts/$name"
    ErrorLog "/var/log/httpd/$name.error_log"
    CustomLog "/var/log/httpd/$name.access_log" combined
</VirtualHost>
</Macro>

Macro names are case-insensitive, like httpd configuration directives. However, variable names are case sensitive.

You would then invoke this macro several times to create virtual hosts:

Use VHost example example.com
Use VHost myhost hostname.org
Use VHost apache apache.org

UndefMacro VHost

At server startup time, each of these Use invocations would be expanded into a full virtualhost, as described by the <Macro> definition.

The UndefMacro directive is used so that later macros using the same variable names don't result in conflicting definitions.

A more elaborate version of this example may be seen below in the Examples section.

Tips

Parameter names should begin with a sigil such as $, %, or @, so that they are clearly identifiable, and also in order to help deal with interactions with other directives, such as the core Define directive. Failure to do so will result in a warning. Nevertheless, you are encouraged to have a good knowledge of your entire server configuration in order to avoid reusing the same variables in different scopes, which can cause confusion.

Parameters prefixed with either $ or % are not escaped. Parameters prefixes with @ are escaped in quotes.

Avoid using a parameter which contains another parameter as a prefix, (For example, $win and $winter) as this may cause confusion at expression evaluation time. In the event of such confusion, the longest possible parameter name is used.

If you want to use a value within another string, it is useful to surround the parameter in braces, to avoid confusion:

<Macro DocRoot ${docroot}>
    DocumentRoot "/var/www/${docroot}/htdocs"
</Macro>

Examples

Virtual Host Definition

A common usage of mod_macro is for the creation of dynamically-generated virtual hosts.

## Define a VHost Macro for repetitive configurations

<Macro VHost $host $port $dir>
  Listen $port
  <VirtualHost *:$port>

    ServerName $host
    DocumentRoot "$dir"

    # Public document root
    <Directory "$dir">
        Require all granted
    </Directory>

    # limit access to intranet subdir.
    <Directory "$dir/intranet">
      Require ip 10.0.0.0/8
    </Directory>
  </VirtualHost>
</Macro>

## Use of VHost with different arguments.

Use VHost www.apache.org 80 /vhosts/apache/htdocs
Use VHost example.org 8080 /vhosts/example/htdocs
Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs

Removal of a macro definition

It's recommended that you undefine a macro once you've used it. This avoids confusion in a complex configuration file where there may be conflicts in variable names.

<Macro DirGroup $dir $group>
  <Directory "$dir">
    Require group $group
  </Directory>
</Macro>

Use DirGroup /www/apache/private private
Use DirGroup /www/apache/server  admin

UndefMacro DirGroup

<Macro> Directive

Description: | Define a configuration file macro
Syntax: | <Macro name [par1 .. parN]> ... </Macro>
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_macro

The <Macro> directive controls the definition of a macro within the server runtime configuration files. The first argument is the name of the macro. Other arguments are parameters to the macro. It is good practice to prefix parameter names with any of '$%@', and not macro names with such characters.

<Macro LocalAccessPolicy>
    Require ip 10.2.16.0/24
</Macro>

<Macro RestrictedAccessPolicy $ipnumbers>
    Require ip $ipnumbers
</Macro>

UndefMacro Directive

Description: | Undefine a macro
Syntax: | UndefMacro name
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_macro

The UndefMacro directive undefines a macro which has been defined before hand.

UndefMacro LocalAccessPolicy
UndefMacro RestrictedAccessPolicy

Use Directive

Description: | Use a macro
Syntax: | Use name [value1 ... valueN]
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_macro

The Use directive controls the use of a macro. The specified macro is expanded. It must be given the same number of arguments as in the macro definition. The provided values are associated to their corresponding initial parameters and are substituted before processing.

Use LocalAccessPolicy
...
Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"

is equivalent, with the macros defined above, to:

Require ip 10.2.16.0/24
...
Require ip 192.54.172.0/24 192.54.148.0/24


mod_mime - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_mime

Description: | Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding)
Status: | Base
Module Identifier: | mime_module
Source File: | mod_mime.c

Summary

This module is used to assign content metadata to the content selected for an HTTP response by mapping patterns in the URI or filenames to the metadata values. For example, the filename extensions of content files often define the content's Internet media type, language, character set, and content-encoding. This information is sent in HTTP messages containing that content and used in content negotiation when selecting alternatives, such that the user's preferences are respected when choosing one of several possible contents to serve. See mod_negotiation for more information about content negotiation.

The directives AddCharset, AddEncoding, AddLanguage and AddType are all used to map file extensions onto the metadata for that file. Respectively they set the character set, content-encoding, content-language, and media-type (content-type) of documents. The directive TypesConfig is used to specify a file which also maps extensions onto media types.

In addition, mod_mime may define the handler and filters that originate and process content. The directives AddHandler, AddOutputFilter, and AddInputFilter control the modules or scripts that serve the document. The MultiviewsMatch directive allows mod_negotiation to consider these file extensions to be included when testing Multiviews matches.

While mod_mime associates metadata with filename extensions, the core server provides directives that are used to associate all the files in a given container (e.g., <Location>, <Directory>, or <Files>) with particular metadata. These directives include ForceType, SetHandler, SetInputFilter, and SetOutputFilter. The core directives override any filename extension mappings defined in mod_mime.

Note that changing the metadata for a file does not change the value of the Last-Modified header. Thus, previously cached copies may still be used by a client or proxy, with the previous headers. If you change the metadata (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.

See also

  • MimeMagicFile
  • AddDefaultCharset
  • ForceType
  • SetHandler
  • SetInputFilter
  • SetOutputFilter

Files with Multiple Extensions

Files can have more than one extension; the order of the extensions is normally irrelevant. For example, if the file welcome.html.fr maps onto content type text/html and language French then the file welcome.fr.html will map onto exactly the same information. If more than one extension is given that maps onto the same type of metadata, then the one to the right will be used, except for languages and content encodings. For example, if .gif maps to the media-type image/gif and .html maps to the media-type text/html, then the file welcome.gif.html will be associated with the media-type text/html.

Languages and content encodings are treated accumulative, because one can assign more than one language or encoding to a particular resource. For example, the file welcome.html.en.de will be delivered with Content-Language: en, de and Content-Type: text/html.

Care should be taken when a file with multiple extensions gets associated with both a media-type and a handler. This will usually result in the request being handled by the module associated with the handler. For example, if the .imap extension is mapped to the handler imap-file (from mod_imagemap) and the .html extension is mapped to the media-type text/html, then the file world.imap.html will be associated with both the imap-file handler and text/html media-type. When it is processed, the imap-file handler will be used, and so it will be treated as a mod_imagemap imagemap file.

If you would prefer only the last dot-separated part of the filename to be mapped to a particular piece of meta-data, then do not use the Add* directives. For example, if you wish to have the file foo.html.cgi processed as a CGI script, but not the file bar.cgi.html, then instead of using AddHandler cgi-script .cgi, use

Configure handler based on final extension only

<FilesMatch "[^.]+\.cgi$">
  SetHandler cgi-script
</FilesMatch>

Content encoding

A file of a particular media-type can additionally be encoded a particular way to simplify transmission over the Internet. While this usually will refer to compression, such as gzip, it can also refer to encryption, such a pgp or to an encoding such as UUencoding, which is designed for transmitting a binary file in an ASCII (text) format.

The HTTP/1.1 RFC, section 14.11 puts it this way:

The Content-Encoding entity-header field is used as a modifier to the media-type. When present, its value indicates what additional content codings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type.

By using more than one file extension (see section above about multiple file extensions), you can indicate that a file is of a particular type, and also has a particular encoding.

For example, you may have a file which is a Microsoft Word document, which is pkzipped to reduce its size. If the .doc extension is associated with the Microsoft Word file type, and the .zip extension is associated with the pkzip file encoding, then the file Resume.doc.zip would be known to be a pkzip'ed Word document.

Apache sends a Content-encoding header with the resource, in order to tell the client browser about the encoding method.

Content-encoding: pkzip

Character sets and languages

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.

The character set, language, encoding and mime type are all used in the process of content negotiation (See mod_negotiation) 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 AddCharset, AddEncoding, AddLanguage and AddType directives (and extensions listed in the MimeMagicFile) participate in this select process. Filename extensions that are only associated using the AddHandler, AddInputFilter or AddOutputFilter directives may be included or excluded from matching by using the MultiviewsMatch directive.

Charset

To convey this further information, Apache optionally sends a Content-Language header, to specify the language that the document is in, and can append additional information onto the Content-Type header to indicate the particular character set that should be used to correctly render the information.

Content-Language: en, fr Content-Type: text/plain; charset=ISO-8859-1

The language specification is the two-letter abbreviation for the language. The charset is the name of the particular character set which should be used.

AddCharset Directive

Description: | Maps the given filename extensions to the specified content charset
Syntax: | AddCharset charset extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddCharset directive maps the given filename extensions to the specified content charset (the Internet registered name for a given character encoding). charset is the media type's charset parameter for resources with filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

Example

AddLanguage ja .ja
AddCharset EUC-JP .euc
AddCharset ISO-2022-JP .jis
AddCharset SHIFT_JIS .sjis

Then the document xxxx.ja.jis will be treated as being a Japanese document whose charset is ISO-2022-JP (as will the document xxxx.jis.ja). 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 content negotiation, where the server returns one from several documents based on the client's charset preference.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

See also

  • mod_negotiation
  • AddDefaultCharset

AddEncoding Directive

Description: | Maps the given filename extensions to the specified encoding type
Syntax: | AddEncoding encoding extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddEncoding directive maps the given filename extensions to the specified HTTP content-encoding. encoding is the HTTP content coding to append to the value of the Content-Encoding header field for documents named with the extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

Example

AddEncoding x-gzip .gz
AddEncoding x-compress .Z

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.

Old clients expect x-gzip and x-compress, however the standard dictates that they're equivalent to gzip and compress respectively. Apache does content encoding comparisons by ignoring any leading x-. When responding with an encoding Apache will use whatever form (i.e., x-foo or foo) the client requested. If the client didn't specifically request a particular form Apache will use the form given by the AddEncoding directive. To make this long story short, you should always use x-gzip and x-compress for these two specific encodings. More recent encodings, such as deflate, should be specified without the x-.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

AddHandler Directive

Description: | Maps the filename extensions to the specified handler
Syntax: | AddHandler handler-name extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

Files having the name extension will be served by the specified handler-name. This mapping is added to any already in force, overriding any mappings that already exist for the same extension. For example, to activate CGI scripts with the file extension .cgi, you might use:

AddHandler cgi-script .cgi

Once that has been put into your httpd.conf file, any file containing the .cgi extension will be treated as a CGI program.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

See also

  • SetHandler

AddInputFilter Directive

Description: | Maps filename extensions to the filters that will process client requests
Syntax: | AddInputFilter filter[;filter...] extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

AddInputFilter maps the filename extension extension to the 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 SetInputFilter directive. This mapping is merged over any already in force, overriding any mappings that already exist for the same extension.

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content. The filter is case-insensitive.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

See also

  • RemoveInputFilter
  • SetInputFilter

AddLanguage Directive

Description: | Maps the given filename extension to the specified content language
Syntax: | AddLanguage language-tag extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddLanguage directive maps the given filename extension to the specified content language. Files with the filename extension are assigned an HTTP Content-Language value of language-tag corresponding to the language identifiers defined by RFC 3066. This directive overrides any mappings that already exist for the same extension.

Example

AddEncoding x-compress .Z
AddLanguage en .en
AddLanguage fr .fr

Then the document xxxx.en.Z will be treated as being a compressed English document (as will the document xxxx.Z.en). Although the content language is reported to the client, the browser is unlikely to use this information. The AddLanguage directive is more useful for content negotiation, where the server returns one from several documents based on the client's language preference.

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:

AddLanguage en .en
AddLanguage en-gb .en
AddLanguage en-us .en

documents with the extension .en would be treated as being en-us.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

See also

  • mod_negotiation

AddOutputFilter Directive

Description: | Maps filename extensions to the filters that will process responses from the server
Syntax: | AddOutputFilter filter[;filter...] extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddOutputFilter directive maps the filename extension extension 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 SetOutputFilter and AddOutputFilterByType directive. This mapping is merged over any already in force, overriding any mappings that already exist for the same extension.

For example, the following configuration will process all .shtml files for server-side includes and will then compress the output using mod_deflate.

AddOutputFilter INCLUDES;DEFLATE shtml

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content. The filter argument is case-insensitive.

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

Note that when defining a set of filters using the AddOutputFilter directive, any definition made will replace any previous definition made by the AddOutputFilter directive.

# Effective filter "DEFLATE"
AddOutputFilter DEFLATE shtml
<Location "/foo">
  # Effective filter "INCLUDES", replacing "DEFLATE"
  AddOutputFilter INCLUDES shtml
</Location>
<Location "/bar">
  # Effective filter "INCLUDES;DEFLATE", replacing "DEFLATE"
  AddOutputFilter INCLUDES;DEFLATE shtml
</Location>
<Location "/bar/baz">
  # Effective filter "BUFFER", replacing "INCLUDES;DEFLATE"
  AddOutputFilter BUFFER shtml
</Location>
<Location "/bar/baz/buz">
  # No effective filter, replacing "BUFFER"
  RemoveOutputFilter shtml
</Location>

See also

  • RemoveOutputFilter
  • SetOutputFilter

AddType Directive

Description: | Maps the given filename extensions onto the specified content type
Syntax: | AddType media-type extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddType directive maps the given filename extensions onto the specified content type. media-type is the media type to use for filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

It is recommended that new media types be added using the AddType directive rather than changing the TypesConfig file.

Example

AddType image/gif .gif

Or, to specify multiple file extensions in one directive:

Example

AddType image/jpeg jpeg jpg jpe

The extension argument is case-insensitive and can be specified with or without a leading dot. Filenames may have multiple extensions and the extension argument will be compared against each of them.

A simmilar effect to mod_negotiation's LanguagePriority can be achieved by qualifying a media-type with qs:

Example

AddType application/rss+xml;qs=0.8 .xml

This is useful in situations, e.g. when a client requesting Accept: */* can not actually processes the content returned by the server.

This directive primarily configures the content types generated for static files served out of the filesystem. For resources other than static files, where the generator of the response typically specifies a Content-Type, this directive has no effect.

Note

If no handler is explicitly set for a request, the specified content type will also be used as the handler name.

When explicit directives such as SetHandler or AddHandler do not apply to the current request, the internal handler name normally set by those directives is instead set to the content type specified by this directive.

This is a historical behavior that may be used by some third-party modules (such as mod_php) for taking responsibility for the matching request.

Configurations that rely on such "synthetic" types should be avoided. Additionally, configurations that restrict access to SetHandler or AddHandler should restrict access to this directive as well.

See also

  • ForceType
  • mod_negotiation

DefaultLanguage Directive

Description: | Defines a default language-tag to be sent in the Content-Language header field for all resources in the current context that have not been assigned a language-tag by some other means.
Syntax: | DefaultLanguage language-tag
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The DefaultLanguage directive tells Apache that all resources in the directive's scope (e.g., all resources covered by the current <Directory> container) that don't have an explicit language extension (such as .fr or .de as configured by AddLanguage) should be assigned a Content-Language of language-tag. This allows entire directory trees to be marked as containing Dutch content, for instance, without having to rename each file. Note that unlike using extensions to specify languages, DefaultLanguage can only specify a single language.

If no DefaultLanguage directive is in force and a file does not have any language extensions as configured by AddLanguage, then no Content-Language header field will be generated.

Example

DefaultLanguage en

See also

  • mod_negotiation

ModMimeUsePathInfo Directive

Description: | Tells mod_mime to treat path_info components as part of the filename
Syntax: | ModMimeUsePathInfo On|Off
Default: | ModMimeUsePathInfo Off
Context: | directory
Status: | Base
Module: | mod_mime

The ModMimeUsePathInfo directive is used to combine the filename with the path_info URL component to apply mod_mime's directives to the request. The default value is Off - therefore, the path_info component is ignored.

This directive is recommended when you have a virtual filesystem.

Example

ModMimeUsePathInfo On

If you have a request for /index.php/foo.shtml mod_mime will now treat the incoming request as /index.php/foo.shtml and directives like AddOutputFilter INCLUDES .shtml will add the INCLUDES filter to the request. If ModMimeUsePathInfo is not set, the INCLUDES filter will not be added. This will work analogously for virtual paths, such as those defined by <Location>

See also

  • AcceptPathInfo

MultiviewsMatch Directive

Description: | The types of files that will be included when searching for a matching file with MultiViews
Syntax: | MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters]
Default: | MultiviewsMatch NegotiatedOnly
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

MultiviewsMatch permits three different behaviors for mod_negotiation'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.

The NegotiatedOnly option provides that every extension following the base name must correlate to a recognized mod_mime extension for content negotiation, e.g. Charset, Content-Type, Language, or Encoding. This is the strictest implementation with the fewest unexpected side effects, and is the default behavior.

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 bytes 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.

You may finally allow Any extensions to match, even if mod_mime doesn't recognize the extension. This can cause unpredictable results, such as serving .old or .bak files the webmaster never expected to be served.

For example, the following configuration will allow handlers and filters to participate in Multviews, but will exclude unknown files:

MultiviewsMatch Handlers Filters

MultiviewsMatch is not allowed in a <Location> or <LocationMatch> section.

See also

  • Options
  • mod_negotiation

RemoveCharset Directive

Description: | Removes any character set associations for a set of file extensions
Syntax: | RemoveCharset extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveCharset directive removes any character set associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive and can be specified with or without a leading dot.

Example

RemoveCharset .html .shtml

RemoveEncoding Directive

Description: | Removes any content encoding associations for a set of file extensions
Syntax: | RemoveEncoding extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveEncoding directive removes any encoding associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

AddEncoding x-gzip .gz
AddType text/plain .asc
<Files "*.gz.asc">
    RemoveEncoding .gz
</Files>

This will cause foo.gz to be marked as being encoded with the gzip method, but foo.gz.asc as an unencoded plaintext file.

Note

RemoveEncoding directives are processed after any AddEncoding directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.

The extension argument is case-insensitive and can be specified with or without a leading dot.

RemoveHandler Directive

Description: | Removes any handler associations for a set of file extensions
Syntax: | RemoveHandler extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveHandler directive removes any handler associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

AddHandler server-parsed .html

/foo/bar/.htaccess:

RemoveHandler .html

This has the effect of returning .html files in the /foo/bar directory to being treated as normal files, rather than as candidates for parsing (see the mod_include module).

The extension argument is case-insensitive and can be specified with or without a leading dot.

RemoveInputFilter Directive

Description: | Removes any input filter associations for a set of file extensions
Syntax: | RemoveInputFilter extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveInputFilter directive removes any input filter associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive and can be specified with or without a leading dot.

See also

  • AddInputFilter
  • SetInputFilter

RemoveLanguage Directive

Description: | Removes any language associations for a set of file extensions
Syntax: | RemoveLanguage extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveLanguage directive removes any language associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive and can be specified with or without a leading dot.

RemoveOutputFilter Directive

Description: | Removes any output filter associations for a set of file extensions
Syntax: | RemoveOutputFilter extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveOutputFilter directive removes any output filter associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive and can be specified with or without a leading dot.

Example

RemoveOutputFilter shtml

See also

  • AddOutputFilter

RemoveType Directive

Description: | Removes any content type associations for a set of file extensions
Syntax: | RemoveType extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveType directive removes any media type associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

RemoveType .cgi

This will remove any special handling of .cgi files in the /foo/ directory and any beneath it, causing responses containing those files to omit the HTTP Content-Type header field.

Note

RemoveType directives are processed after any AddType directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.

The extension argument is case-insensitive and can be specified with or without a leading dot.

TypesConfig Directive

Description: | The location of the mime.types file
Syntax: | TypesConfig file-path
Default: | TypesConfig conf/mime.types
Context: | server config
Status: | Base
Module: | mod_mime

The TypesConfig directive sets the location of the media types configuration file. File-path is relative to the ServerRoot. This file sets the default list of mappings from filename extensions to content types. Most administrators use the mime.types file provided by their OS, which associates common filename extensions with the official list of IANA registered media types maintained at http://www.iana.org/assignments/media-types/index.html as well as a large number of unofficial types. This simplifies the httpd.conf file by providing the majority of media-type definitions, and may be overridden by AddType directives as needed. You should not edit the mime.types file, because it may be replaced when you upgrade your server.

The file contains lines in the format of the arguments to an AddType directive:

media-type [extension] ...

The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#) are ignored. Empty lines are there for completeness (of the mime.types file). Apache httpd can still determine these types with mod_mime_magic.

Please do not send requests to the Apache HTTP Server 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.

See also

  • mod_mime_magic


mod_mime_magic - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_mime_magic

Description: | Determines the MIME type of a file by looking at a few bytes of its contents
Status: | Extension
Module Identifier: | mime_magic_module
Source File: | mod_mime_magic.c

Summary

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 mod_mime can't resolve.

This module is derived from a free version of the file(1) 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 MimeMagicFile directive.

Format of the Magic File

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:

Column | Description
1 byte number to begin checking from
">" indicates a dependency upon the previous non-">" line
2

type of data to match

byte | single character
short | machine-order 16-bit integer
long | machine-order 32-bit integer
string | arbitrary-length string
date | long integer date (seconds since Unix epoch/1970)
beshort | big-endian 16-bit integer
belong | big-endian 32-bit integer
bedate | big-endian 32-bit integer date
leshort | little-endian 16-bit integer
lelong | little-endian 32-bit integer
ledate | little-endian 32-bit integer date
3 | contents of data to match
4 | MIME type if matched
5 | MIME encoding if matched (optional)

For example, the following magic file lines would recognize some audio formats:

# 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

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.)

# 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

An optional MIME encoding can be included as a fifth column. For example, this can recognize gzipped files and set the encoding for them.

# gzip (GNU zip, not to be confused with
#       [Info-ZIP/PKWARE] zip archiver)

0  string  \037\213  application/octet-stream  x-gzip

Performance Issues

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.

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.

Notes

The following notes apply to the mod_mime_magic module and are included here for compliance with contributors' copyright restrictions that require their acknowledgment.

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. (i.e., 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.

MimeMagicFile Directive

Description: | Enable MIME-type determination based on file contents using the specified magic file
Syntax: | MimeMagicFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_mime_magic

The MimeMagicFile directive can be used to enable this module, the default file is distributed at conf/magic. 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.

Example

MimeMagicFile conf/magic

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_negotiation - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_negotiation

Description: | Provides for content negotiation
Status: | Base
Module Identifier: | negotiation_module
Source File: | mod_negotiation.c

Summary

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.

  • A type map (a file with the handler type-map) which explicitly lists the files containing the variants.
  • A Multiviews search (enabled by the Multiviews Options), where the server does an implicit filename pattern match, and choose from amongst the results.

See also

  • Options
  • mod_mime
  • Content Negotiation
  • Environment Variables

Type maps

A type map has a format similar to 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:

Content-Encoding:
The encoding of the file. Apache only recognizes encodings that are defined by an AddEncoding directive. This normally includes the encodings x-compress for compress'd files, and x-gzip for gzip'd files. The x- prefix is ignored for encoding comparisons.
Content-Language:
The language(s) of the variant, as an Internet standard language tag (RFC 1766). An example is en, meaning English. If the variant contains more than one language, they are separated by a comma.
Content-Length:
The length of the file, in bytes. If this header is not present, then the actual length of the file is used.
Content-Type:
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 name=value. Common parameters include:
level
an integer specifying the version of the media type. For text/html this defaults to 2, otherwise 0.
qs
a floating-point number with a value in the range 0[.000] to 1[.000], 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.

Example

Content-Type: image/jpeg; qs=0.8

URI:
uri of the file containing the variant (of the given media type, encoded with the given content encoding). These are interpreted as URLs relative to the map file; they must be on the same server, and they must refer to files to which the client would be granted access if they were to be requested directly.
Body:
The actual content of the resource may be included in the type-map file using the Body header. This header must contain a string that designates a delimiter for the body content. Then all following lines in the type map file will be considered part of the resource body until the delimiter string is found.

Example:

Body:----xyz----
<html>
<body>
<p>Content of the page.</p>
</body>
</html>
----xyz----

Consider, for example, a resource called document.html which is available in English, French, and German. The files for each of these are called document.html.en, document.html.fr, and document.html.de, respectively. The type map file will be called document.html.var, and will contain the following:

URI: document.html

Content-language: en
Content-type: text/html
URI: document.html.en

Content-language: fr
Content-type: text/html
URI: document.html.fr

Content-language: de
Content-type: text/html
URI: document.html.de

All four of these files should be placed in the same directory, and the .var file should be associated with the type-map handler with an AddHandler directive:

AddHandler type-map .var

A request for document.html.var in this directory will result in choosing the variant which most closely matches the language preference specified in the user's Accept-Language request header.

If Multiviews is enabled, and MultiviewsMatch is set to "handlers" or "any", a request to document.html will discover document.html.var and continue negotiating with the explicit type map.

Other configuration directives, such as Alias can be used to map document.html to document.html.var.

Multiviews

A Multiviews search is enabled by the Multiviews Options. If the server receives a request for /some/dir/foo and /some/dir/foo does not exist, then the server reads the directory looking for all files named foo.*, 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.

The MultiviewsMatch directive configures whether Apache will consider files that do not have content negotiation meta-information assigned to them when choosing files.

CacheNegotiatedDocs Directive

Description: | Allows content-negotiated documents to be cached by proxy servers
Syntax: | CacheNegotiatedDocs On|Off
Default: | CacheNegotiatedDocs Off
Context: | server config, virtual host
Status: | Base
Module: | mod_negotiation

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.

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.

ForceLanguagePriority Directive

Description: | Action to take if a single acceptable document is not found
Syntax: | ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]
Default: | ForceLanguagePriority Prefer
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_negotiation

The ForceLanguagePriority directive uses the given LanguagePriority to satisfy negotiation where the server could otherwise not return a single matching document.

ForceLanguagePriority Prefer uses LanguagePriority 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 the first matching variant, en, will be served.

LanguagePriority en fr de
ForceLanguagePriority Prefer

ForceLanguagePriority Fallback uses LanguagePriority 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 language response, but such a variant isn't found, then the first variant from the LanguagePriority list below will be served.

LanguagePriority en fr de
ForceLanguagePriority Fallback

Both options, Prefer and Fallback, may be specified, so either the first matching variant from LanguagePriority will be served if more than one variant is acceptable, or first available document will be served if none of the variants matched the client's acceptable list of languages.

See also

  • AddLanguage

LanguagePriority Directive

Description: | The precendence of language variants for cases where the client does not express a preference
Syntax: | LanguagePriority MIME-lang [MIME-lang] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_negotiation

The LanguagePriority 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 MIME-lang are in order of decreasing preference.

LanguagePriority en fr de

For a request for foo.html, where foo.html.fr and foo.html.de both existed, but the browser did not express a language preference, then foo.html.fr would be returned.

Note that this directive only has an effect if a 'best' language cannot be determined by any other means or the ForceLanguagePriority directive is not None. In general, the client determines the language preference, not the server.

See also

  • AddLanguage


mod_nw_ssl - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_nw_ssl

Description: | Enable SSL encryption for NetWare
Status: | Base
Module Identifier: | nwssl_module
Source File: | mod_nw_ssl.c
Compatibility: | NetWare only

Summary

This module enables SSL encryption for a specified port. It takes advantage of the SSL encryption functionality that is built into the NetWare operating system.

NWSSLTrustedCerts Directive

Description: | List of additional client certificates
Syntax: | NWSSLTrustedCerts filename [filename] ...
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Specifies a list of client certificate files (DER format) that are used when creating a proxied SSL connection. Each client certificate used by a server must be listed separately in its own .der file.

NWSSLUpgradeable Directive

Description: | Allows a connection to be upgraded to an SSL connection upon request
Syntax: | NWSSLUpgradeable [IP-address:]portnumber
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Allow a connection that was created on the specified address and/or port to be upgraded to an SSL connection upon request from the client. The address and/or port must have already be defined previously with a Listen directive.

SecureListen Directive

Description: | Enables SSL encryption for the specified port
Syntax: | SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL]
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Specifies the port and the eDirectory based certificate name that will be used to enable SSL encryption. An optional third parameter also enables mutual authentication.


mod_privileges - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_privileges

Description: | Support for Solaris privileges and for running virtual hosts under different user IDs.
Status: | Experimental
Module Identifier: | privileges_module
Source File: | mod_privileges.c
Compatibility: | Available in Apache 2.3 and up, on Solaris 10 and OpenSolaris platforms

Summary

This module enables different Virtual Hosts to run with different Unix User and Group IDs, and with different Solaris Privileges. In particular, it offers a solution to the problem of privilege separation between different Virtual Hosts, first promised by the abandoned perchild MPM. It also offers other security enhancements.

Unlike perchild, mod_privileges is not itself an MPM. It works within a processing model to set privileges and User/Group per request in a running process. It is therefore not compatible with a threaded MPM, and will refuse to run under one.

mod_privileges raises security issues similar to those of suexec. But unlike suexec, it applies not only to CGI programs but to the entire request processing cycle, including in-process applications and subprocesses. It is ideally suited to running PHP applications under mod_php, which is also incompatible with threaded MPMs. It is also well-suited to other in-process scripting applications such as mod_perl, mod_python, and mod_ruby, and to applications implemented in C as apache modules where privilege separation is an issue.

Security Considerations

mod_privileges introduces new security concerns in situations where untrusted code may be run within the webserver process. This applies to untrusted modules, and scripts running under modules such as mod_php or mod_perl. Scripts running externally (e.g. as CGI or in an appserver behind mod_proxy or mod_jk) are NOT affected.

The basic security concerns with mod_privileges are:

  • Running as a system user introduces the same security issues as mod_suexec, and near-equivalents such as cgiwrap and suphp.
  • A privileges-aware malicious user extension (module or script) could escalate its privileges to anything available to the httpd process in any virtual host. This introduces new risks if (and only if) mod_privileges is compiled with the BIG_SECURITY_HOLE option.
  • A privileges-aware malicious user extension (module or script) could escalate privileges to set its user ID to another system user (and/or group).

The PrivilegesMode directive allows you to select either FAST or SECURE mode. You can mix modes, using FAST mode for trusted users and fully-audited code paths, while imposing SECURE mode where an untrusted user has scope to introduce code.

Before describing the modes, we should also introduce the target use cases: Benign vs Hostile. In a benign situation, you want to separate users for their convenience, and protect them and the server against the risks posed by honest mistakes, but you trust your users are not deliberately subverting system security. In a hostile situation - e.g. commercial hosting - you may have users deliberately attacking the system or each other.

FAST mode
In FAST mode, requests are run in-process with the selected uid/gid and privileges, so the overhead is negligible. This is suitable for benign situations, but is not secure against an attacker escalating privileges with an in-process module or script.
SECURE mode
A request in SECURE mode forks a subprocess, which then drops privileges. This is a very similar case to running CGI with suexec, but for the entire request cycle, and with the benefit of fine-grained control of privileges.

You can select different PrivilegesModes for each virtual host, and even in a directory context within a virtual host. FAST mode is appropriate where the user(s) are trusted and/or have no privilege to load in-process code. SECURE mode is appropriate to cases where untrusted code might be run in-process. However, even in SECURE mode, there is no protection against a malicious user who is able to introduce privileges-aware code running before the start of the request-processing cycle.

DTracePrivileges Directive

Description: | Determines whether the privileges required by dtrace are enabled.
Syntax: | DTracePrivileges On|Off
Default: | DTracePrivileges Off
Context: | server config
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

This server-wide directive determines whether Apache will run with the privileges required to run dtrace. Note that DTracePrivileges On will not in itself activate DTrace, but DTracePrivileges Off will prevent it working.

PrivilegesMode Directive

Description: | Trade off processing speed and efficiency vs security against malicious privileges-aware code.
Syntax: | PrivilegesMode FAST|SECURE|SELECTIVE
Default: | PrivilegesMode FAST
Context: | server config, virtual host, directory
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

This directive trades off performance vs security against malicious, privileges-aware code. In SECURE mode, each request runs in a secure subprocess, incurring a substantial performance penalty. In FAST mode, the server is not protected against escalation of privileges as discussed above.

This directive differs slightly between a <Directory> context (including equivalents such as Location/Files/If) and a top-level or <VirtualHost>.

At top-level, it sets a default that will be inherited by virtualhosts. In a virtual host, FAST or SECURE mode acts on the entire HTTP request, and any settings in a <Directory> context will be ignored. A third pseudo-mode SELECTIVE defers the choice of FAST vs SECURE to directives in a <Directory> context.

In a <Directory> context, it is applicable only where SELECTIVE mode was set for the VirtualHost. Only FAST or SECURE can be set in this context (SELECTIVE would be meaningless).

Warning

Where SELECTIVE mode is selected for a virtual host, the activation of privileges must be deferred until after the mapping phase of request processing has determined what <Directory> context applies to the request. This might give an attacker opportunities to introduce code through a RewriteMap running at top-level or <VirtualHost> context before privileges have been dropped and userid/gid set.

VHostCGIMode Directive

Description: | Determines whether the virtualhost can run subprocesses, and the privileges available to subprocesses.
Syntax: | VHostCGIMode On|Off|Secure
Default: | VHostCGIMode On
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

Determines whether the virtual host is allowed to run fork and exec, the privileges required to run subprocesses. If this is set to Off the virtualhost is denied the privileges and will not be able to run traditional CGI programs or scripts under the traditional mod_cgi, nor similar external programs such as those created by mod_ext_filter or RewriteMap prog. Note that it does not prevent CGI programs running under alternative process and security models such as mod_fcgid, which is a recommended solution in Solaris.

If set to On or Secure, the virtual host is permitted to run external programs and scripts as above. Setting VHostCGIMode Secure has the effect of denying privileges to the subprocesses, as described for VHostSecure.

VHostCGIPrivs Directive

Description: | Assign arbitrary privileges to subprocesses created by a virtual host.
Syntax: | VHostPrivs [+-]?privilege-name [[+-]?privilege-name] ...
Default: | None
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM) and when mod_privileges is compiled with the BIG_SECURITY_HOLE compile-time option.

VHostCGIPrivs can be used to assign arbitrary privileges to subprocesses created by a virtual host, as discussed under VHostCGIMode. Each privilege-name is the name of a Solaris privilege, such as file_setid or sys_nfs.

A privilege-name may optionally be prefixed by + or -, which will respectively allow or deny a privilege. If used with neither + nor -, all privileges otherwise assigned to the virtualhost will be denied. You can use this to override any of the default sets and construct your own privilege set.

Security

This directive can open huge security holes in apache subprocesses, up to and including running them with root-level powers. Do not use it unless you fully understand what you are doing!

VHostGroup Directive

Description: | Sets the Group ID under which a virtual host runs.
Syntax: | VHostGroup unix-groupid
Default: | Inherits the group id specified in Group
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

The VHostGroup directive sets the Unix group under which the server will process requests to a virtualhost. The group is set before the request is processed and reset afterwards using Solaris Privileges. Since the setting applies to the process, this is not compatible with threaded MPMs.

Unix-group is one of:

A group name
Refers to the given group by name.
# followed by a group number.
Refers to a group by its number.

Security

This directive cannot be used to run apache as root! Nevertheless, it opens potential security issues similar to those discussed in the suexec documentation.

See also

  • Group
  • SuexecUserGroup

VHostPrivs Directive

Description: | Assign arbitrary privileges to a virtual host.
Syntax: | VHostPrivs [+-]?privilege-name [[+-]?privilege-name] ...
Default: | None
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM) and when mod_privileges is compiled with the BIG_SECURITY_HOLE compile-time option.

VHostPrivs can be used to assign arbitrary privileges to a virtual host. Each privilege-name is the name of a Solaris privilege, such as file_setid or sys_nfs.

A privilege-name may optionally be prefixed by + or -, which will respectively allow or deny a privilege. If used with neither + nor -, all privileges otherwise assigned to the virtualhost will be denied. You can use this to override any of the default sets and construct your own privilege set.

Security

This directive can open huge security holes in apache, up to and including running requests with root-level powers. Do not use it unless you fully understand what you are doing!

VHostSecure Directive

Description: | Determines whether the server runs with enhanced security for the virtualhost.
Syntax: | VHostSecure On|Off
Default: | VHostSecure On
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

Determines whether the virtual host processes requests with security enhanced by removal of Privileges that are rarely needed in a webserver, but which are available by default to a normal Unix user and may therefore be required by modules and applications. It is recommended that you retain the default (On) unless it prevents an application running. Since the setting applies to the process, this is not compatible with threaded MPMs.

Note

If VHostSecure prevents an application running, this may be a warning sign that the application should be reviewed for security.

VHostUser Directive

Description: | Sets the User ID under which a virtual host runs.
Syntax: | VHostUser unix-userid
Default: | Inherits the userid specified in User
Context: | virtual host
Status: | Experimental
Module: | mod_privileges
Compatibility: | Available on Solaris 10 and OpenSolaris with non-threaded MPMs (prefork or custom MPM).

The VHostUser directive sets the Unix userid under which the server will process requests to a virtualhost. The userid is set before the request is processed and reset afterwards using Solaris Privileges. Since the setting applies to the process, this is not compatible with threaded MPMs.

Unix-userid is one of:

A username
Refers to the given user by name.
# followed by a user number.
Refers to a user by its number.

Security

This directive cannot be used to run apache as root! Nevertheless, it opens potential security issues similar to those discussed in the suexec documentation.

See also

  • User
  • SuexecUserGroup


mod_proxy - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy

Description: | Multi-protocol proxy/gateway server
Status: | Extension
Module Identifier: | proxy_module
Source File: | mod_proxy.c

Summary

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

mod_proxy and related modules implement a proxy/gateway for Apache HTTP Server, supporting a number of popular protocols as well as several different load balancing algorithms. Third-party modules can add support for additional protocols and load balancing algorithms.

A set of modules must be loaded into the server to provide the necessary features. These modules can be included statically at build time or dynamically via the LoadModule directive). The set must include:

  • mod_proxy, which provides basic proxy capabilities
  • mod_proxy_balancer and one or more balancer modules if load balancing is required. (See mod_proxy_balancer for more information.)
  • one or more proxy scheme, or protocol, modules:
    Protocol | Module
    AJP13 (Apache JServe Protocol version 1.3) | mod_proxy_ajp
    CONNECT (for SSL) | mod_proxy_connect
    FastCGI | mod_proxy_fcgi
    ftp | mod_proxy_ftp
    HTTP/0.9, HTTP/1.0, and HTTP/1.1 | mod_proxy_http
    SCGI | mod_proxy_scgi
    WS and WSS (Web-sockets) | mod_proxy_wstunnel

In addition, extended features are provided by other modules. Caching is provided by mod_cache and related modules. The ability to contact remote servers using the SSL/TLS protocol is provided by the SSLProxy* directives of mod_ssl. These additional modules will need to be loaded and configured to take advantage of these features.

See also

  • mod_cache
  • mod_proxy_ajp
  • mod_proxy_connect
  • mod_proxy_fcgi
  • mod_proxy_ftp
  • mod_proxy_http
  • mod_proxy_scgi
  • mod_proxy_wstunnel
  • mod_proxy_balancer
  • mod_ssl

Forward Proxies and Reverse Proxies/Gateways

Apache HTTP Server can be configured in both a forward and reverse proxy (also known as gateway) mode.

An ordinary forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the origin server, the client sends a request to the proxy naming the origin server as the target. The proxy then requests the content from the origin server and returns it to the client. The client must be specially configured to use the forward proxy to access other sites.

A typical usage of a forward proxy is to provide Internet access to internal clients that are otherwise restricted by a firewall. The forward proxy can also use caching (as provided by mod_cache) to reduce network usage.

The forward proxy is activated using the ProxyRequests directive. Because forward proxies allow clients to access arbitrary sites through your server and to hide their true origin, it is essential that you secure your server so that only authorized clients can access the proxy before activating a forward proxy.

A reverse proxy (or gateway), by contrast, appears to the client just like an ordinary web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the namespace of the reverse proxy. The reverse proxy then decides where to send those requests and returns the content as if it were itself the origin.

A typical usage of a reverse proxy is to provide Internet users access to a server that is behind a firewall. Reverse proxies can also be used to balance load among several back-end servers or to provide caching for a slower back-end server. In addition, reverse proxies can be used simply to bring several servers into the same URL space.

A reverse proxy is activated using the ProxyPass directive or the [P] flag to the RewriteRule directive. It is not necessary to turn ProxyRequests on in order to configure a reverse proxy.

Basic Examples

The examples below are only a very basic idea to help you get started. Please read the documentation on the individual directives.

In addition, if you wish to have caching enabled, consult the documentation from mod_cache.

Reverse Proxy

ProxyPass "/foo" "http://foo.example.com/bar"
ProxyPassReverse "/foo" "http://foo.example.com/bar"

Forward Proxy

ProxyRequests On
ProxyVia On

<Proxy "*">
  Require host internal.example.com
</Proxy>

Access via Handler

You can also force a request to be handled as a reverse-proxy request, by creating a suitable Handler pass-through. The example configuration below will pass all requests for PHP scripts to the specified FastCGI server using reverse proxy:

Reverse Proxy PHP scripts

<FilesMatch "\.php$">
    # Unix sockets require 2.4.7 or later
    SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
</FilesMatch>

This feature is available in Apache HTTP Server 2.4.10 and later.

Workers

The proxy manages the configuration of origin servers and their communication parameters in objects called workers. There are two built-in workers: the default forward proxy worker and the default reverse proxy worker. Additional workers can be configured explicitly.

The two default workers have a fixed configuration and will be used if no other worker matches the request. They do not use HTTP Keep-Alive or connection pooling. The TCP connections to the origin server will instead be opened and closed for each request.

Explicitly configured workers are identified by their URL. They are usually created and configured using ProxyPass or ProxyPassMatch when used for a reverse proxy:

ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30

This will create a worker associated with the origin server URL http://backend.example.com that will use the given timeout values. When used in a forward proxy, workers are usually defined via the ProxySet directive:

ProxySet "http://backend.example.com" connectiontimeout=5 timeout=30

or alternatively using Proxy and ProxySet:

<Proxy "http://backend.example.com">
  ProxySet connectiontimeout=5 timeout=30
</Proxy>

Using explicitly configured workers in the forward mode is not very common, because forward proxies usually communicate with many different origin servers. Creating explicit workers for some of the origin servers can still be useful if they are used very often. Explicitly configured workers have no concept of forward or reverse proxying by themselves. They encapsulate a common concept of communication with origin servers. A worker created by ProxyPass for use in a reverse proxy will also be used for forward proxy requests whenever the URL to the origin server matches the worker URL, and vice versa.

The URL identifying a direct worker is the URL of its origin server including any path components given:

ProxyPass "/examples" "http://backend.example.com/examples"
ProxyPass "/docs" "http://backend.example.com/docs"

This example defines two different workers, each using a separate connection pool and configuration.

Worker Sharing

Worker sharing happens if the worker URLs overlap, which occurs when the URL of some worker is a leading substring of the URL of another worker defined later in the configuration file. In the following example

ProxyPass "/apps" "http://backend.example.com/" timeout=60
ProxyPass "/examples" "http://backend.example.com/examples" timeout=10

the second worker isn't actually created. Instead the first worker is used. The benefit is, that there is only one connection pool, so connections are more often reused. Note that all configuration attributes given explicitly for the later worker will be ignored. This will be logged as a warning. In the above example, the resulting timeout value for the URL /examples will be 60 instead of 10!

If you want to avoid worker sharing, sort your worker definitions by URL length, starting with the longest worker URLs. If you want to maximize worker sharing, use the reverse sort order. See also the related warning about ordering ProxyPass directives.

Explicitly configured workers come in two flavors: direct workers and (load) balancer workers. They support many important configuration attributes which are described below in the ProxyPass directive. The same attributes can also be set using ProxySet.

The set of options available for a direct worker depends on the protocol which is specified in the origin server URL. Available protocols include ajp, fcgi, ftp, http and scgi.

Balancer workers are virtual workers that use direct workers known as their members to actually handle the requests. Each balancer can have multiple members. When it handles a request, it chooses a member based on the configured load balancing algorithm.

A balancer worker is created if its worker URL uses balancer as the protocol scheme. The balancer URL uniquely identifies the balancer worker. Members are added to a balancer using BalancerMember.

Controlling Access to Your Proxy

You can control who can access your proxy via the <Proxy> control block as in the following example:

<Proxy "*">
  Require ip 192.168.0
</Proxy>

For more information on access control directives, see mod_authz_host.

Strictly limiting access is essential if you are using a forward proxy (using the ProxyRequests directive). Otherwise, your server can be used by any client to access arbitrary hosts while hiding his or her true identity. This is dangerous both for your network and for the Internet at large. When using a reverse proxy (using the ProxyPass directive with ProxyRequests Off), access control is less critical because clients can only contact the hosts that you have specifically configured.

See Also the Proxy-Chain-Auth environment variable.

Slow Startup

If you're using the ProxyBlock 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.

Intranet Proxy

An Apache httpd proxy server situated in an intranet needs to forward external requests through the company's firewall (for this, configure the ProxyRemote directive to forward the respective scheme to the firewall proxy). However, when it has to access resources within the intranet, it can bypass the firewall when accessing hosts. The NoProxy directive is useful for specifying which hosts belong to the intranet and should be accessed directly.

Users within an intranet tend to omit the local domain name from their WWW requests, thus requesting "http://somehost/" instead of http://somehost.example.com/. Some commercial proxy servers let them get away with this and simply serve the request, implying a configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache httpd 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.

Protocol Adjustments

For circumstances where mod_proxy is sending requests to an origin server that doesn't properly implement keepalives or HTTP/1.1, there are two environment variables that can force the request to use HTTP/1.0 with no keepalive. These are set via the SetEnv directive.

These are the force-proxy-request-1.0 and proxy-nokeepalive notes.

<Location "/buggyappserver/">
  ProxyPass "http://buggyappserver:7001/foo/"
  SetEnv force-proxy-request-1.0 1
  SetEnv proxy-nokeepalive 1
</Location>

Request Bodies

Some request methods such as POST include a request body. The HTTP protocol requires that requests which include a body either use chunked transfer encoding or send a Content-Length request header. When passing these requests on to the origin server, mod_proxy_http will always attempt to send the Content-Length. But if the body is large and the original request used chunked encoding, then chunked encoding may also be used in the upstream request. You can control this selection using environment variables. Setting proxy-sendcl ensures maximum compatibility with upstream servers by always sending the Content-Length, while setting proxy-sendchunked minimizes resource usage by using chunked encoding.

Under some circumstances, the server must spool request bodies to disk to satisfy the requested handling of request bodies. For example, this spooling will occur if the original body was sent with chunked encoding (and is large), but the administrator has asked for backend requests to be sent with Content-Length or as HTTP/1.0. This spooling can also occur if the request body already has a Content-Length header, but the server is configured to filter incoming request bodies.

LimitRequestBody only applies to request bodies that the server will spool to disk

Reverse Proxy Request Headers

When acting in a reverse-proxy mode (using the ProxyPass directive, for example), mod_proxy_http adds several request headers in order to pass information to the origin server. These headers are:

X-Forwarded-For
The IP address of the client.
X-Forwarded-Host
The original host requested by the client in the Host HTTP request header.
X-Forwarded-Server
The hostname of the proxy server.

Be careful when using these headers on the origin server, since they will contain more than one (comma-separated) value if the original request already contained one of these headers. For example, you can use %{X-Forwarded-For}i in the log format string of the origin server to log the original clients IP address, but you may get more than one address if the request passes through several proxies.

See also the ProxyPreserveHost and ProxyVia directives, which control other request headers.

Note: If you need to specify custom request headers to be added to the forwarded request, use the RequestHeader directive.

BalancerGrowth Directive

Description: | Number of additional Balancers that can be added Post-configuration
Syntax: | BalancerGrowth #
Default: | BalancerGrowth 5
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | BalancerGrowth is only available in Apache HTTP Server 2.3.13 and later.

This directive allows for growth potential in the number of Balancers available for a virtualhost in addition to the number pre-configured. It only takes effect if there is at least one pre-configured Balancer.

BalancerInherit Directive

Description: | Inherit ProxyPassed Balancers/Workers from the main server
Syntax: | BalancerInherit On|Off
Default: | BalancerInherit On
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.

This directive will cause the current server/vhost to "inherit" ProxyPass Balancers and Workers defined in the main server. This can cause issues and inconsistent behavior if using the Balancer Manager and so should be disabled if using that feature.

The setting in the global server defines the default for all vhosts.

BalancerMember Directive

Description: | Add a member to a load balancing group
Syntax: | BalancerMember [balancerurl] url [key=value [key=value ...]]
Context: | directory
Status: | Extension
Module: | mod_proxy
Compatibility: | BalancerMember is only available in Apache HTTP Server 2.2 and later.

This directive adds a member to a load balancing group. It can be used within a <Proxy balancer://...> container directive and can take any of the key value pair parameters available to ProxyPass directives.

One additional parameter is available only to BalancerMember directives: loadfactor. This is the member load factor - a number between 1 (default) and 100, which defines the weighted load to be applied to the member in question.

The balancerurl is only needed when not within a <Proxy balancer://...> container directive. It corresponds to the url of a balancer defined in ProxyPass directive.

The path component of the balancer URL in any <Proxy balancer://...> container directive is ignored.

Trailing slashes should typically be removed from the URL of a BalancerMember.

BalancerPersist Directive

Description: | Attempt to persist changes made by the Balancer Manager across restarts.
Syntax: | BalancerPersist On|Off
Default: | BalancerPersist Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.

This directive will cause the shared memory storage associated with the balancers and balancer members to be persisted across restarts. This allows these local changes to not be lost during the normal restart/graceful state transitions.

NoProxy Directive

Description: | Hosts, domains, or networks that will be connected to directly
Syntax: | NoProxy host [host] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache httpd proxy servers within intranets. The NoProxy 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 ProxyRemote proxy server(s).

Example

ProxyRemote  "*"  "http://firewall.example.com:81"
NoProxy         ".example.com" "192.168.112.0/21"

The host arguments to the NoProxy directive are one of the following type list:

Domain

A Domain 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 (i.e., the suffixes of the hostnames are all ending in Domain).

Examples

.com .example.org.

To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can have a DNS A record, too!), Domains are always written with a leading period.

Note

Domain name comparisons are done without regard to the case, and Domains are always assumed to be anchored in the root of the DNS tree; therefore, the two domains .ExAmple.com and .example.com. (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.

SubNet

A SubNet 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 SubNet. 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.) Examples:

192.168 or 192.168.0.0
the subnet 192.168.0.0 with an implied netmask of 16 valid bits (sometimes used in the netmask form 255.255.0.0)
192.168.112.0/21
the subnet 192.168.112.0/21 with a netmask of 21 valid bits (also used in the form 255.255.248.0)

As a degenerate case, a SubNet with 32 valid bits is the equivalent to an IPAddr, while a SubNet with zero valid bits (e.g., 0.0.0.0/0) is the same as the constant _Default_, matching any IP address.

IPAddr

A IPAddr 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.

Example

192.168.123.7

Note

An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance.

Hostname

A Hostname is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the DNS domain name service. It represents a logical host (in contrast to Domains, see above) and must be resolvable to at least one IPAddr (or often to a list of hosts with different IPAddrs).

Examples

prep.ai.example.edu
www.example.org

Note

In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable deal of time when the connection to the name server uses a slow PPP link.

Hostname comparisons are done without regard to the case, and Hostnames are always assumed to be anchored in the root of the DNS tree; therefore, the two hosts WWW.ExAmple.com and www.example.com. (note the trailing period) are considered equal.

See also

  • DNS Issues

<Proxy> Directive

Description: | Container for directives applied to proxied resources
Syntax: | <Proxy wildcard-url> ...</Proxy>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

Directives placed in <Proxy> sections apply only to matching proxied content. Shell-style wildcards are allowed.

For example, the following will allow only hosts in yournetwork.example.com to access content via your proxy server:

<Proxy "*">
  Require host yournetwork.example.com
</Proxy>

The following example will process all files in the foo directory of example.com through the INCLUDES filter when they are sent through the proxy server:

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

Differences from the Location configuration section

A backend URL matches the configuration section if it begins with the the wildcard-url string, even if the last path segment in the directive only matches a prefix of the backend URL. For example, <Proxy "http://example.com/foo"> matches all of http://example.com/foo, http://example.com/foo/bar, and http://example.com/foobar. The matching of the final URL differs from the behavior of the <Location> section, which for purposes of this note treats the final path component as if it ended in a slash.

For more control over the matching, see <ProxyMatch>.

See also

  • <ProxyMatch>

ProxyAddHeaders Directive

Description: | Add proxy information in X-Forwarded-* headers
Syntax: | ProxyAddHeaders Off|On
Default: | ProxyAddHeaders On
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in version 2.3.10 and later

This directive determines whether or not proxy related information should be passed to the backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.

Effectiveness

This option is of use only for HTTP proxying, as handled by mod_proxy_http.

ProxyBadHeader Directive

Description: | Determines how to handle bad header lines in a response
Syntax: | ProxyBadHeader IsError|Ignore|StartBody
Default: | ProxyBadHeader IsError
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyBadHeader directive determines the behavior of mod_proxy if it receives syntactically invalid response header lines (i.e. containing no colon) from the origin server. The following arguments are possible:

IsError
Abort the request and end up with a 502 (Bad Gateway) response. This is the default behavior.
Ignore
Treat bad header lines as if they weren't sent.
StartBody
When receiving the first bad header line, finish reading the headers and treat the remainder as body. This helps to work around buggy backend servers which forget to insert an empty line between the headers and the body.

ProxyBlock Directive

Description: | Words, hosts, or domains that are banned from being proxied
Syntax: | ProxyBlock *|word|host|domain [word|host|domain] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyBlock 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 blocked 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. That may slow down the startup time of the server.

Example

ProxyBlock "news.example.com" "auctions.example.com" "friends.example.com"

Note that example would also be sufficient to match any of these sites.

Hosts would also be matched if referenced by IP address.

Note also that

ProxyBlock "*"

blocks connections to all sites.

ProxyDomain Directive

Description: | Default domain name for proxied requests
Syntax: | ProxyDomain Domain
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache httpd proxy servers within intranets. The ProxyDomain 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 Domain appended will be generated.

Example

      ProxyRemote  "*"  "http://firewall.example.com:81"

      NoProxy         ".example.com" "192.168.112.0/21"

      ProxyDomain     ".example.com"

ProxyErrorOverride Directive

Description: | Override error pages for proxied content
Syntax: | ProxyErrorOverride On|Off
Default: | ProxyErrorOverride Off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

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.)

This directive does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses.

ProxyIOBufferSize Directive

Description: | Determine size of internal data throughput buffer
Syntax: | ProxyIOBufferSize bytes
Default: | ProxyIOBufferSize 8192
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyIOBufferSize directive adjusts the size of the internal buffer which is used as a scratchpad for the data between input and output. The size must be at least 512.

In almost every case, there's no reason to change that value.

If used with AJP, this directive sets the maximum AJP packet size in bytes. Values larger than 65536 are set to 65536. If you change it from the default, you must also change the packetSize attribute of your AJP connector on the Tomcat side! The attribute packetSize is only available in Tomcat 5.5.20+ and 6.0.2+

Normally it is not necessary to change the maximum packet size. Problems with the default value have been reported when sending certificates or certificate chains.

<ProxyMatch> Directive

Description: | Container for directives applied to regular-expression-matched proxied resources
Syntax: | <ProxyMatch regex> ...</ProxyMatch>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

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

From 2.4.8 onwards, named groups and backreferences are captured and written to the environment with the corresponding name prefixed with "MATCH_" and in upper case. This allows elements of URLs to be referenced from within expressions and modules like mod_rewrite. In order to prevent confusion, numbered (unnamed) backreferences are ignored. Use named groups instead.

<ProxyMatch "^http://(?<sitename>[^/]+)">
    Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</ProxyMatch>

See also

  • <Proxy>

ProxyMaxForwards Directive

Description: | Maximium number of proxies that a request can be forwarded through
Syntax: | ProxyMaxForwards number
Default: | ProxyMaxForwards -1
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Default behaviour changed in 2.2.7

The ProxyMaxForwards directive specifies the maximum number of proxies through which a request may pass if there's no Max-Forwards header supplied with the request. This may be set to prevent infinite proxy loops or a DoS attack.

Example

ProxyMaxForwards 15

Note that setting ProxyMaxForwards is a violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy setting Max-Forwards if the Client didn't set it. Earlier Apache httpd versions would always set it. A negative ProxyMaxForwards value, including the default -1, gives you protocol-compliant behavior but may leave you open to loops.

ProxyPass Directive

Description: | Maps remote servers into the local server URL-space
Syntax: | ProxyPass [path] !|url [key=value [key=value ...]] [nocanon] [interpolate] [noquery]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy
Compatibility: | Unix Domain Socket (UDS) support added in 2.4.7

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. The local server is often called a reverse proxy or gateway. The path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string.

Note: This directive cannot be used within a <Directory> context.
The ProxyRequests directive should usually be set off when using ProxyPass.

In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target which prepends unix:/path/lis.sock|. For example, to proxy HTTP and target the UDS at /home/www/socket, you would use unix:/home/www.socket|http://localhost/whatever/.

Note: The path associated with the unix: URL is DefaultRuntimeDir aware.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>. The same will occur inside a <LocationMatch> section; however, ProxyPass does not interpret the regexp as such, so it is necessary to use ProxyPassMatch in this situation instead.

Suppose the local server has address http://example.com/; then

<Location "/mirror/foo/">
    ProxyPass "http://backend.example.com/"
</Location>

will cause a local request for http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar.

The ProxyPass directive is not supported in <Directory> or <Files> sections.

If you require a more flexible reverse-proxy configuration, see the RewriteRule directive with the [P] flag.

The following alternative syntax is possible; however, it can carry a performance penalty when present in very large numbers. The advantage of the below syntax is that it allows for dynamic control via the Balancer Manager interface:

ProxyPass "/mirror/foo/" "http://backend.example.com/"

If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results.

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory, e.g.

<Location "/mirror/foo/">
    ProxyPass "http://backend.example.com/"
</Location>
<Location "/mirror/foo/i">
    ProxyPass "!"
</Location>
ProxyPass "/mirror/foo/i" "!"
ProxyPass "/mirror/foo" "http://backend.example.com"

will proxy all requests to /mirror/foo to backend.example.com except requests made to /mirror/foo/i.

Ordering ProxyPass Directives

The configured ProxyPass and ProxyPassMatch rules are checked in the order of configuration. The first rule that matches wins. So usually you should sort conflicting ProxyPass rules starting with the longest URLs first. Otherwise, later rules for longer URLS will be hidden by any earlier rule which uses a leading substring of the URL. Note that there is some relation with worker sharing. In contrast, only one ProxyPass directive can be placed in a Location block, and the most specific location will take precedence.

For the same reasons, exclusions must come before the general ProxyPass directives.

ProxyPass key=value Parameters

In Apache HTTP Server 2.1 and later, mod_proxy supports pooled connections to a backend server. Connections created on demand can be retained in a pool for future use. Limits on the pool size and other settings can be coded on the ProxyPass directive using key=value parameters, described in the tables below.

By default, mod_proxy will allow and retain the maximum number of connections that could be used simultaneously by that web server child process. Use the max parameter to reduce the number from the default. Use the ttl parameter to set an optional time to live; connections which have been unused for at least ttl seconds will be closed. ttl can be used to avoid using a connection which is subject to closing because of the backend server's keep-alive timeout.

The pool of connections is maintained per web server child process, and max and other settings are not coordinated among all child processes, except when only one child process is allowed by configuration or MPM design.

Example

ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
BalancerMember parameters
Parameter | Default | Description
min | 0 | Minimum number of connection pool entries, unrelated to the actual number of connections. This only needs to be modified from the default for special circumstances where heap memory associated with the backend connections should be preallocated or retained.
max | 1...n | Maximum number of connections that will be allowed to the backend server. The default for this limit is the number of threads per process in the active MPM. In the Prefork MPM, this is always 1, while with other MPMs, it is controlled by the ThreadsPerChild directive.
smax | max | Retained connection pool entries above this limit are freed during certain operations if they have been unused for longer than the time to live, controlled by the ttl parameter. If the connection pool entry has an associated connection, it will be closed. This only needs to be modified from the default for special circumstances where connection pool entries and any associated connections which have exceeded the time to live need to be freed or closed more aggressively.
acquire - If set, this will be the maximum time to wait for a free connection in the connection pool, in milliseconds. If there are no free connections in the pool, the Apache httpd will return SERVER_BUSY status to the client.
connectiontimeout | timeout | Connect timeout in seconds. The number of seconds Apache httpd waits for the creation of a connection to the backend to complete. By adding a postfix of ms, the timeout can be also set in milliseconds.
disablereuse | Off | This parameter should be used when you want to force mod_proxy to immediately close a connection to the backend after being used, and thus, disable its persistent connection and pool for that backend. This helps in various situations where a firewall between Apache httpd and the backend server (regardless of protocol) tends to silently drop connections or when backends themselves may be under round- robin DNS. To disable connection pooling reuse, set this property value to On.
enablereuse | On | This is the inverse of 'disablereuse' above, provided as a convenience for scheme handlers that require opt-in for connection reuse (such as mod_proxy_fcgi). 2.4.11 and later only.
flushpackets | off | Determines whether the proxy module will auto-flush the output brigade after each "chunk" of data. 'off' means that it will flush only when needed; 'on' means after each chunk is sent; and 'auto' means poll/wait for a period of time and flush if no input has been received for 'flushwait' milliseconds. Currently, this is in effect only for AJP.
flushwait | 10 | The time to wait for additional input, in milliseconds, before flushing the output brigade if 'flushpackets' is 'auto'.
iobuffersize | 8192 | Adjusts the size of the internal scratchpad IO buffer. This allows you to override the ProxyIOBufferSize for a specific worker. This must be at least 512 or set to 0 for the system default of 8192.
keepalive Off

This parameter should be used when you have a firewall between your Apache httpd and the backend server, which tends to drop inactive connections. This flag will tell the Operating System to send KEEP_ALIVE messages on inactive connections and thus prevent the firewall from dropping the connection. To enable keepalive, set this property value to On.

The frequency of initial and subsequent TCP keepalive probes depends on global OS settings, and may be as high as 2 hours. To be useful, the frequency configured in the OS must be smaller than the threshold used by the firewall.

lbset | 0 | Sets the load balancer cluster set that the worker is a member of. The load balancer will try all members of a lower numbered lbset before trying higher numbered ones.
ping | 0 | Ping property tells the webserver to "test" the connection to the backend before forwarding the request. For AJP, it causes mod_proxy_ajp to send a CPING request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+). For HTTP, it causes mod_proxy_http to send a 100-Continue to the backend (only valid for HTTP/1.1 - for non HTTP/1.1 backends, this property has no effect). In both cases, the parameter is the delay in seconds to wait for the reply. This feature has been added to avoid problems with hung and busy backends. This will increase the network traffic during the normal operation which could be an issue, but it will lower the traffic in case some of the cluster nodes are down or busy. By adding a postfix of ms, the delay can be also set in milliseconds.
receivebuffersize | 0 | Adjusts the size of the explicit (TCP/IP) network buffer size for proxied connections. This allows you to override the ProxyReceiveBufferSize for a specific worker. This must be at least 512 or set to 0 for the system default.
redirect - Redirection Route of the worker. This value is usually set dynamically to enable safe removal of the node from the cluster. If set, all requests without session id will be redirected to the BalancerMember that has route parameter equal to this value.
retry | 60 | Connection pool worker retry timeout in seconds. If the connection pool worker to the backend server is in the error state, Apache httpd will not forward any requests to that server until the timeout expires. This enables to shut down the backend server for maintenance and bring it back online later. A value of 0 means always retry workers in an error state with no timeout.
route - Route of the worker when used inside load balancer. The route is a value appended to session id.
status - Single letter value defining the initial status of this worker.
D: Worker is disabled and will not accept any requests.
S: Worker is administratively stopped.
I: Worker is in ignore-errors mode and will always be considered available.
H: Worker is in hot-standby mode and will only be used if no other viable workers are available.
E: Worker is in an error state.
N: Worker is in drain mode and will only accept existing sticky sessions destined for itself and ignore all other requests.
Status can be set (which is the default) by prepending with '+' or cleared by prepending with '-'. Thus, a setting of 'S-E' sets this worker to Stopped and clears the in-error flag.
timeout | ProxyTimeout | Connection timeout in seconds. The number of seconds Apache httpd waits for data sent by / to the backend.
ttl - Time to live for inactive connections and associated connection pool entries, in seconds. Once reaching this limit, a connection will not be used again; it will be closed at some later time.
flusher flush

Name of the provider used by mod_proxy_fdpass. See the documentation of this module for more details.

If the Proxy directive scheme starts with the balancer:// (eg: balancer://cluster, any path information is ignored), then a virtual worker that does not really communicate with the backend server will be created. Instead, it is responsible for the management of several "real" workers. In that case, the special set of parameters can be added to this virtual worker. See mod_proxy_balancer for more information about how the balancer works.

Balancer parameters
Parameter | Default | Description
lbmethod | byrequests | Balancer load-balance method. Select the load-balancing scheduler method to use. Either byrequests, to perform weighted request counting; bytraffic, to perform weighted traffic byte count balancing; or bybusyness, to perform pending request balancing. The default is byrequests.
maxattempts | One less than the number of workers, or 1 with a single worker. | Maximum number of failover attempts before giving up.
nofailover | Off | If set to On, the session will break if the worker is in error state or disabled. Set this value to On if backend servers do not support session replication.
stickysession - Balancer sticky session name. The value is usually set to something like JSESSIONID or PHPSESSIONID, and it depends on the backend application server that support sessions. If the backend application server uses different name for cookies and url encoded id (like servlet containers) use | to separate them. The first part is for the cookie the second for the path.
Available in Apache HTTP Server 2.4.4 and later.
stickysessionsep "." Sets the separation symbol in the session cookie. Some backend application servers do not use the '.' as the symbol. For example, the Oracle Weblogic server uses '!'. The correct symbol can be set using this option. The setting of 'Off' signifies that no symbol is used.
scolonpathdelim | Off | If set to On, the semi-colon character ';' will be used as an additional sticky session path delimiter/separator. This is mainly used to emulate mod_jk's behavior when dealing with paths such as JSESSIONID=6736bcf34;foo=aabfa
timeout | 0 | Balancer timeout in seconds. If set, this will be the maximum time to wait for a free worker. The default is to not wait.
failonstatus - A single or comma-separated list of HTTP status codes. If set, this will force the worker into error state when the backend returns any status code in the list. Worker recovery behaves the same as other worker errors.
failontimeout Off If set, an IO read timeout after a request is sent to the backend will force the worker into error state. Worker recovery behaves the same as other worker errors.
Available in Apache HTTP Server 2.4.5 and later.
nonce <auto> The protective nonce used in the balancer-manager application page. The default is to use an automatically determined UUID-based nonce, to provide for further protection for the page. If set, then the nonce is set to that value. A setting of None disables all nonce checking.

Note

In addition to the nonce, the balancer-manager page should be protected via an ACL.

growth | 0 | Number of additional BalancerMembers to allow to be added to this balancer in addition to those defined at configuration.
forcerecovery On Force the immediate recovery of all workers without considering the retry parameter of the workers if all workers of a balancer are in error state. There might be cases where an already overloaded backend can get into deeper trouble if the recovery of all workers is enforced without considering the retry parameter of each worker. In this case, set to Off.
Available in Apache HTTP Server 2.4.2 and later.

A sample balancer setup:

ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
<Proxy "balancer://mycluster">
    BalancerMember "ajp://1.2.3.4:8009"
    BalancerMember "ajp://1.2.3.5:8009" loadfactor=20
    # Less powerful server, don't send as many requests there,
    BalancerMember "ajp://1.2.3.6:8009" loadfactor=5
</Proxy>

Setting up a hot-standby that will only be used if no other members are available:

ProxyPass "/" "balancer://hotcluster/"
<Proxy "balancer://hotcluster">
    BalancerMember "ajp://1.2.3.4:8009" loadfactor=1
    BalancerMember "ajp://1.2.3.5:8009" loadfactor=2
    # The server below is on hot standby
    BalancerMember "ajp://1.2.3.6:8009" status=+H
    ProxySet lbmethod=bytraffic
</Proxy>

Additional ProxyPass Keywords

Normally, mod_proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those that make use of PATH_INFO. The optional nocanon keyword suppresses this and passes the URL path "raw" to the backend. Note that this keyword may affect the security of your backend, as it removes the normal limited protection against URL-based attacks provided by the proxy.

Normally, mod_proxy will include the query string when generating the SCRIPT_FILENAME environment variable. The optional noquery keyword (available in httpd 2.4.1 and later) prevents this.

The optional interpolate keyword, in combination with ProxyPassInterpolateEnv, causes the ProxyPass to interpolate environment variables, using the syntax ${VARNAME}. Note that many of the standard CGI-derived environment variables will not exist when this interpolation happens, so you may still have to resort to mod_rewrite for complex rules. Also note that interpolation is not supported within the scheme portion of a URL. Dynamic determination of the scheme can be accomplished with mod_rewrite as in the following example.

RewriteEngine On

RewriteCond "%{HTTPS}" =off
RewriteRule "." "-" [E=protocol:http]
RewriteCond "%{HTTPS}" =on
RewriteRule "." "-" [E=protocol:https]

RewriteRule "^/mirror/foo/(.*)" "%{ENV:protocol}://backend.example.com/$1" [P]
ProxyPassReverse  "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverse  "/mirror/foo/" "https://backend.example.com/"

ProxyPassInherit Directive

Description: | Inherit ProxyPass directives defined from the main server
Syntax: | ProxyPassInherit On|Off
Default: | ProxyPassInherit On
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later.

This directive will cause the current server/vhost to "inherit" ProxyPass directives defined in the main server. This can cause issues and inconsistent behavior if using the Balancer Manager for dynamic changes and so should be disabled if using that feature.

The setting in the global server defines the default for all vhosts.

Disabling ProxyPassInherit also disables BalancerInherit.

ProxyPassInterpolateEnv Directive

Description: | Enable Environment Variable interpolation in Reverse Proxy configurations
Syntax: | ProxyPassInterpolateEnv On|Off
Default: | ProxyPassInterpolateEnv Off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in httpd 2.2.9 and later

This directive, together with the interpolate argument to ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain, and ProxyPassReverseCookiePath, enables reverse proxies to be dynamically configured using environment variables which may be set by another module such as mod_rewrite. It affects the ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain, and ProxyPassReverseCookiePath directives and causes them to substitute the value of an environment variable varname for the string ${varname} in configuration directives if the interpolate option is set.

Keep this turned off (for server performance) unless you need it!

ProxyPassMatch Directive

Description: | Maps remote servers into the local server URL-space using regular expressions
Syntax: | ProxyPassMatch [regex] !|url [key=value [key=value ...]]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive is equivalent to ProxyPass but makes use of regular expressions instead of simple prefix matching. The supplied regular expression is matched against the url, and if it matches, the server will substitute any parenthesized matches into the given string and use it as a new url.

Note: This directive cannot be used within a <Directory> context.

Suppose the local server has address http://example.com/; then

ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com/$1"

will cause a local request for http://example.com/foo/bar.gif to be internally converted into a proxy request to http://backend.example.com/foo/bar.gif.

Note

The URL argument must be parsable as a URL before regexp substitutions (as well as after). This limits the matches you can use. For instance, if we had used

ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"

in our previous example, it would fail with a syntax error at server startup. This is a bug (PR 46665 in the ASF bugzilla), and the workaround is to reformulate the match:

ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory.

When used inside a <LocationMatch> section, the first argument is omitted and the regexp is obtained from the <LocationMatch>.

If you require a more flexible reverse-proxy configuration, see the RewriteRule directive with the [P] flag.

Default Substitution

When the URL parameter doesn't use any backreferences into the regular expression, the original URL will be appended to the URL parameter.

Security Warning

Take care when constructing the target URL of the rule, considering the security impact from allowing the client influence over the set of URLs to which your server will act as a proxy. Ensure that the scheme and hostname part of the URL is either fixed or does not allow the client undue influence.

ProxyPassReverse Directive

Description: | Adjusts the URL in HTTP response headers sent from a reverse proxied server
Syntax: | ProxyPassReverse [path] url [interpolate]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive lets Apache httpd adjust the URL in the Location, Content-Location and URI headers on HTTP redirect responses. This is essential when Apache httpd is used as a reverse proxy (or gateway) to avoid bypassing the reverse proxy because of HTTP redirects on the backend servers which stay behind the reverse proxy.

Only the HTTP response headers specifically mentioned above will be rewritten. Apache httpd will not rewrite other response headers, nor will it by default rewrite URL references inside HTML pages. This means that if the proxied content contains absolute URL references, they will bypass the proxy. To rewrite HTML content to match the proxy, you must load and enable mod_proxy_html.

path is the name of a local virtual path; url is a partial URL for the remote server. These parameters are used the same way as for the ProxyPass directive.

For example, suppose the local server has address http://example.com/; then

ProxyPass         "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverse  "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverseCookieDomain  "backend.example.com"  "public.example.com"
ProxyPassReverseCookiePath  "/"  "/mirror/foo/"

will not only cause a local request for the http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar (the functionality which ProxyPass provides here). It also takes care of redirects which the server backend.example.com sends when redirecting http://backend.example.com/bar to http://backend.example.com/quux . Apache httpd adjusts this to http://example.com/mirror/foo/quux before forwarding the HTTP redirect response to the client. Note that the hostname used for constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.

Note that this ProxyPassReverse directive can also be used in conjunction with the proxy feature (RewriteRule ... [P]) from mod_rewrite because it doesn't depend on a corresponding ProxyPass directive.

The optional interpolate keyword, used together with ProxyPassInterpolateEnv, enables interpolation of environment variables specified using the format ${VARNAME}. Note that interpolation is not supported within the scheme portion of a URL.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>. The same occurs inside a <LocationMatch> section, but will probably not work as intended, as ProxyPassReverse will interpret the regexp literally as a path; if needed in this situation, specify the ProxyPassReverse outside the section or in a separate <Location> section.

This directive is not supported in <Directory> or <Files> sections.

ProxyPassReverseCookieDomain Directive

Description: | Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server
Syntax: | ProxyPassReverseCookieDomain internal-domain public-domain [interpolate]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

Usage is basically similar to ProxyPassReverse, but instead of rewriting headers that are a URL, this rewrites the domain string in Set-Cookie headers.

ProxyPassReverseCookiePath Directive

Description: | Adjusts the Path string in Set-Cookie headers from a reverse- proxied server
Syntax: | ProxyPassReverseCookiePath internal-path public-path [interpolate]
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

Useful in conjunction with ProxyPassReverse in situations where backend URL paths are mapped to public paths on the reverse proxy. This directive rewrites the path string in Set-Cookie headers. If the beginning of the cookie path matches internal-path, the cookie path will be replaced with public-path.

In the example given with ProxyPassReverse, the directive:

ProxyPassReverseCookiePath  "/"  "/mirror/foo/"

will rewrite a cookie with backend path / (or /example or, in fact, anything) to /mirror/foo/.

ProxyPreserveHost Directive

Description: | Use incoming Host HTTP request header for proxy request
Syntax: | ProxyPreserveHost On|Off
Default: | ProxyPreserveHost Off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy
Compatibility: | Usable in directory context in 2.3.3 and later.

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.

This option should normally be turned Off. It is mostly useful in special configurations like proxied mass name-based virtual hosting, where the original Host header needs to be evaluated by the backend server.

ProxyReceiveBufferSize Directive

Description: | Network buffer size for proxied HTTP and FTP connections
Syntax: | ProxyReceiveBufferSize bytes
Default: | ProxyReceiveBufferSize 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyReceiveBufferSize directive specifies an explicit (TCP/IP) network buffer size for proxied 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.

Example

ProxyReceiveBufferSize 2048

ProxyRemote Directive

Description: | Remote proxy used to handle certain requests
Syntax: | ProxyRemote match remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This defines remote proxies to this proxy. match 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. remote-server is a partial URL for the remote server. Syntax:

remote-server = scheme://hostname[:port]

scheme is effectively the protocol that should be used to communicate with the remote server; only http and https are supported by this module. When using https, the requests are forwarded through the remote proxy using the HTTP CONNECT method.

Example

ProxyRemote "http://goodguys.example.com/" "http://mirrorguys.example.com:8000"
ProxyRemote "*" "http://cleverproxy.localdomain"
ProxyRemote "ftp" "http://ftpproxy.mydomain:8080"

In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle them.

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.

ProxyRemoteMatch Directive

Description: | Remote proxy used to handle requests matched by regular expressions
Syntax: | ProxyRemoteMatch regex remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyRemoteMatch is identical to the ProxyRemote directive, except that the first argument is a regular expression match against the requested URL.

ProxyRequests Directive

Description: | Enables forward (standard) proxy requests
Syntax: | ProxyRequests On|Off
Default: | ProxyRequests Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This allows or prevents Apache httpd from functioning as a forward proxy server. (Setting ProxyRequests to Off does not disable use of the ProxyPass directive.)

In a typical reverse proxy or gateway configuration, this option should be set to Off.

In order to get the functionality of proxying HTTP or FTP sites, you need also mod_proxy_http or mod_proxy_ftp (or both) present in the server.

In order to get the functionality of (forward) proxying HTTPS sites, you need mod_proxy_connect enabled in the server.

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • Forward and Reverse Proxies/Gateways

ProxySet Directive

Description: | Set various Proxy balancer or member parameters
Syntax: | ProxySet url key=value [key=value ...]
Context: | directory
Status: | Extension
Module: | mod_proxy
Compatibility: | ProxySet is only available in Apache HTTP Server 2.2 and later.

This directive is used as an alternate method of setting any of the parameters available to Proxy balancers and workers normally done via the ProxyPass directive. If used within a <Proxy balancer url|worker url> container directive, the url argument is not required. As a side effect the respective balancer or worker gets created. This can be useful when doing reverse proxying via a RewriteRule instead of a ProxyPass directive.

<Proxy "balancer://hotcluster">
    BalancerMember "http://www2.example.com:8080" loadfactor=1
    BalancerMember "http://www3.example.com:8080" loadfactor=2
    ProxySet lbmethod=bytraffic
</Proxy>
<Proxy "http://backend">
    ProxySet keepalive=On
</Proxy>
ProxySet "balancer://foo" lbmethod=bytraffic timeout=15
ProxySet "ajp://backend:7001" timeout=15

Warning

Keep in mind that the same parameter key can have a different meaning depending whether it is applied to a balancer or a worker, as shown by the two examples above regarding timeout.

ProxySourceAddress Directive

Description: | Set local IP address for outgoing proxy connections
Syntax: | ProxySourceAddress address
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in version 2.3.9 and later

This directive allows to set a specific local address to bind to when connecting to a backend server.

ProxyStatus Directive

Description: | Show Proxy LoadBalancer status in mod_status
Syntax: | ProxyStatus Off|On|Full
Default: | ProxyStatus Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in version 2.2 and later

This directive determines whether or not proxy loadbalancer status data is displayed via the mod_status server-status page.

Note

Full is synonymous with On

ProxyTimeout Directive

Description: | Network timeout for proxied requests
Syntax: | ProxyTimeout seconds
Default: | Value of Timeout
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive allows a user to specifiy a timeout on proxy requests. This is useful 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.

ProxyVia Directive

Description: | Information provided in the Via HTTP response header for proxied requests
Syntax: | ProxyVia On|Off|Full|Block
Default: | ProxyVia Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive controls the use of the Via: HTTP header by the proxy. Its intended use is to control the flow of proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section 14.45 for an explanation of Via: header lines.

  • If set to Off, which is the default, no special processing is performed. If a request or reply contains a Via: header, it is passed through unchanged.
  • If set to On, each request and reply will get a Via: header line added for the current host.
  • If set to Full, each generated Via: header line will additionally have the Apache httpd server version shown as a Via: comment field.
  • If set to Block, every proxy request will have all its Via: header lines removed. No new Via: header will be generated.


mod_proxy_ajp - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_ajp

Description: | AJP support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_ajp_module
Source File: | mod_proxy_ajp.c
Compatibility: | Available in version 2.1 and later

Summary

This module requires the service of mod_proxy. It provides support for the Apache JServ Protocol version 1.3 (hereafter AJP13).

Thus, in order to get the ability of handling AJP13 protocol, mod_proxy and mod_proxy_ajp have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy
  • Environment Variable documentation

Usage

This module is used to reverse proxy to a backend application server (e.g. Apache Tomcat) using the AJP13 protocol. The usage is similar to an HTTP reverse proxy, but uses the ajp:// prefix:

Simple Reverse Proxy

ProxyPass "/app" "ajp://backend.example.com:8009/app"

Balancers may also be used:

Balancer Reverse Proxy

<Proxy "balancer://cluster">
    BalancerMember "ajp://app1.example.com:8009" loadfactor=1
    BalancerMember "ajp://app2.example.com:8009" loadfactor=2
    ProxySet lbmethod=bytraffic
</Proxy>
ProxyPass "/app" "balancer://cluster/app"

Note that usually no ProxyPassReverse directive is necessary. The AJP request includes the original host header given to the proxy, and the application server can be expected to generate self-referential headers relative to this host, so no rewriting is necessary.

The main exception is when the URL path on the proxy differs from that on the backend. In this case, a redirect header can be rewritten relative to the original host URL (not the backend ajp:// URL), for example:

Rewriting Proxied Path

ProxyPass "/apps/foo" "ajp://backend.example.com:8009/foo"
ProxyPassReverse "/apps/foo" "http://www.example.com/foo"

However, it is usually better to deploy the application on the backend server at the same path as the proxy rather than to take this approach.

Environment Variables

Environment variables whose names have the prefix AJP_ are forwarded to the origin server as AJP request attributes (with the AJP_ prefix removed from the name of the key).

Overview of the protocol

The AJP13 protocol is packet-oriented. A binary format was presumably chosen over the more readable plain text for reasons of performance. The web server communicates with the servlet container over TCP connections. To cut down on the expensive process of socket creation, the web server will attempt to maintain persistent TCP connections to the servlet container, and to reuse a connection for multiple request/response cycles.

Once a connection is assigned to a particular request, it will not be used for any others until the request-handling cycle has terminated. In other words, requests are not multiplexed over connections. This makes for much simpler code at either end of the connection, although it does cause more connections to be open at once.

Once the web server has opened a connection to the servlet container, the connection can be in one of the following states:

  • Idle
    No request is being handled over this connection.
  • Assigned
    The connection is handling a specific request.

Once a connection is assigned to handle a particular request, the basic request information (e.g. HTTP headers, etc) is sent over the connection in a highly condensed form (e.g. common strings are encoded as integers). Details of that format are below in Request Packet Structure. If there is a body to the request (content-length > 0), that is sent in a separate packet immediately after.

At this point, the servlet container is presumably ready to start processing the request. As it does so, it can send the following messages back to the web server:

  • SEND_HEADERS
    Send a set of headers back to the browser.
  • SEND_BODY_CHUNK
    Send a chunk of body data back to the browser.
  • GET_BODY_CHUNK
    Get further data from the request if it hasn't all been transferred yet. This is necessary because the packets have a fixed maximum size and arbitrary amounts of data can be included the body of a request (for uploaded files, for example). (Note: this is unrelated to HTTP chunked transfer).
  • END_RESPONSE
    Finish the request-handling cycle.

Each message is accompanied by a differently formatted packet of data. See Response Packet Structures below for details.

Basic Packet Structure

There is a bit of an XDR heritage to this protocol, but it differs in lots of ways (no 4 byte alignment, for example).

AJP13 uses network byte order for all data types.

There are four data types in the protocol: bytes, booleans, integers and strings.

Byte
A single byte.
Boolean
A single byte, 1 = true, 0 = false. Using other non-zero values as true (i.e. C-style) may work in some places, but it won't in others.
Integer
A number in the range of 0 to 2^16 (32768). Stored in 2 bytes with the high-order byte first.
String
A variable-sized string (length bounded by 2^16). Encoded with the length packed into two bytes first, followed by the string (including the terminating '\0'). Note that the encoded length does not include the trailing '\0' -- it is like strlen. This is a touch confusing on the Java side, which is littered with odd autoincrement statements to skip over these terminators. I believe the reason this was done was to allow the C code to be extra efficient when reading strings which the servlet container is sending back -- with the terminating \0 character, the C code can pass around references into a single buffer, without copying. if the \0 was missing, the C code would have to copy things out in order to get its notion of a string.

Packet Size

According to much of the code, the max packet size is 8 * 1024 bytes (8K). The actual length of the packet is encoded in the header.

Packet Headers

Packets sent from the server to the container begin with 0x1234. Packets sent from the container to the server begin with AB (that's the ASCII code for A followed by the ASCII code for B). After those first two bytes, there is an integer (encoded as above) with the length of the payload. Although this might suggest that the maximum payload could be as large as 2^16, in fact, the code sets the maximum to be 8K.

Packet Format (Server->Container)
Byte | 0 | 1 | 2 | 3 | 4...(n+3)
Contents | 0x12 | 0x34 | Data Length (n) |  | Data
Packet Format (Container->Server)
Byte | 0 | 1 | 2 | 3 | 4...(n+3)
Contents | A | B | Data Length (n) |  | Data

For most packets, the first byte of the payload encodes the type of message. The exception is for request body packets sent from the server to the container -- they are sent with a standard packet header ( 0x1234 and then length of the packet), but without any prefix code after that.

The web server can send the following messages to the servlet container:

Code | Type of Packet | Meaning
2 | Forward Request | Begin the request-processing cycle with the following data
7 | Shutdown | The web server asks the container to shut itself down.
8 | Ping | The web server asks the container to take control (secure login phase).
10 | CPing | The web server asks the container to respond quickly with a CPong.
none | Data | Size (2 bytes) and corresponding body data.

To ensure some basic security, the container will only actually do the Shutdown if the request comes from the same machine on which it's hosted.

The first Data packet is send immediately after the Forward Request by the web server.

The servlet container can send the following types of messages to the webserver:

Code | Type of Packet | Meaning
3 | Send Body Chunk | Send a chunk of the body from the servlet container to the web server (and presumably, onto the browser).
4 | Send Headers | Send the response headers from the servlet container to the web server (and presumably, onto the browser).
5 | End Response | Marks the end of the response (and thus the request-handling cycle).
6 | Get Body Chunk | Get further data from the request if it hasn't all been transferred yet.
9 | CPong Reply | The reply to a CPing request

Each of the above messages has a different internal structure, detailed below.

Request Packet Structure

For messages from the server to the container of type Forward Request:

AJP13_FORWARD_REQUEST :=
    prefix_code      (byte) 0x02 = JK_AJP13_FORWARD_REQUEST
    method           (byte)
    protocol         (string)
    req_uri          (string)
    remote_addr      (string)
    remote_host      (string)
    server_name      (string)
    server_port      (integer)
    is_ssl           (boolean)
    num_headers      (integer)
    request_headers *(req_header_name req_header_value)
    attributes      *(attribut_name attribute_value)
    request_terminator (byte) OxFF

The request_headers have the following structure:

req_header_name :=
    sc_req_header_name | (string)  [see below for how this is parsed]

sc_req_header_name := 0xA0xx (integer)

req_header_value := (string)

The attributes are optional and have the following structure:

attribute_name := sc_a_name | (sc_a_req_attribute string)

attribute_value := (string)

Not that the all-important header is content-length, because it determines whether or not the container looks for another packet immediately.

Detailed description of the elements of Forward Request

Request prefix

For all requests, this will be 2. See above for details on other Prefix codes.

Method

The HTTP method, encoded as a single byte:

Command Name | Code
OPTIONS | 1
GET | 2
HEAD | 3
POST | 4
PUT | 5
DELETE | 6
TRACE | 7
PROPFIND | 8
PROPPATCH | 9
MKCOL | 10
COPY | 11
MOVE | 12
LOCK | 13
UNLOCK | 14
ACL | 15
REPORT | 16
VERSION-CONTROL | 17
CHECKIN | 18
CHECKOUT | 19
UNCHECKOUT | 20
SEARCH | 21
MKWORKSPACE | 22
UPDATE | 23
LABEL | 24
MERGE | 25
BASELINE_CONTROL | 26
MKACTIVITY | 27

Later version of ajp13, will transport additional methods, even if they are not in this list.

protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl

These are all fairly self-explanatory. Each of these is required, and will be sent for every request.

Headers

The structure of request_headers is the following: First, the number of headers num_headers is encoded. Then, a series of header name req_header_name / value req_header_value pairs follows. Common header names are encoded as integers, to save space. If the header name is not in the list of basic headers, it is encoded normally (as a string, with prefixed length). The list of common headers sc_req_header_nameand their codes is as follows (all are case-sensitive):

Name | Code value | Code name
accept | 0xA001 | SC_REQ_ACCEPT
accept-charset | 0xA002 | SC_REQ_ACCEPT_CHARSET
accept-encoding | 0xA003 | SC_REQ_ACCEPT_ENCODING
accept-language | 0xA004 | SC_REQ_ACCEPT_LANGUAGE
authorization | 0xA005 | SC_REQ_AUTHORIZATION
connection | 0xA006 | SC_REQ_CONNECTION
content-type | 0xA007 | SC_REQ_CONTENT_TYPE
content-length | 0xA008 | SC_REQ_CONTENT_LENGTH
cookie | 0xA009 | SC_REQ_COOKIE
cookie2 | 0xA00A | SC_REQ_COOKIE2
host | 0xA00B | SC_REQ_HOST
pragma | 0xA00C | SC_REQ_PRAGMA
referer | 0xA00D | SC_REQ_REFERER
user-agent | 0xA00E | SC_REQ_USER_AGENT

The Java code that reads this grabs the first two-byte integer and if it sees an '0xA0' in the most significant byte, it uses the integer in the second byte as an index into an array of header names. If the first byte is not 0xA0, it assumes that the two-byte integer is the length of a string, which is then read in.

This works on the assumption that no header names will have length greater than 0x9FFF (==0xA000 - 1), which is perfectly reasonable, though somewhat arbitrary.

Note:

The content-length header is extremely important. If it is present and non-zero, the container assumes that the request has a body (a POST request, for example), and immediately reads a separate packet off the input stream to get that body.

Attributes

The attributes prefixed with a ? (e.g. ?context) are all optional. For each, there is a single byte code to indicate the type of attribute, and then its value (string or integer). They can be sent in any order (though the C code always sends them in the order listed below). A special terminating code is sent to signal the end of the list of optional attributes. The list of byte codes is:

Information | Code Value | Type Of Value | Note
?context | 0x01 | - | Not currently implemented
?servlet_path | 0x02 | - | Not currently implemented
?remote_user | 0x03 | String |
?auth_type | 0x04 | String |
?query_string | 0x05 | String |
?jvm_route | 0x06 | String |
?ssl_cert | 0x07 | String |
?ssl_cipher | 0x08 | String |
?ssl_session | 0x09 | String |
?req_attribute | 0x0A | String | Name (the name of the attribute follows)
?ssl_key_size | 0x0B | Integer |
are_done | 0xFF | - | request_terminator

The context and servlet_path are not currently set by the C code, and most of the Java code completely ignores whatever is sent over for those fields (and some of it will actually break if a string is sent along after one of those codes). I don't know if this is a bug or an unimplemented feature or just vestigial code, but it's missing from both sides of the connection.

The remote_user and auth_type presumably refer to HTTP-level authentication, and communicate the remote user's username and the type of authentication used to establish their identity (e.g. Basic, Digest).

The query_string, ssl_cert, ssl_cipher, and ssl_session refer to the corresponding pieces of HTTP and HTTPS.

The jvm_route, is used to support sticky sessions -- associating a user's sesson with a particular Tomcat instance in the presence of multiple, load-balancing servers.

Beyond this list of basic attributes, any number of other attributes can be sent via the req_attribute code 0x0A. A pair of strings to represent the attribute name and value are sent immediately after each instance of that code. Environment values are passed in via this method.

Finally, after all the attributes have been sent, the attribute terminator, 0xFF, is sent. This signals both the end of the list of attributes and also then end of the Request Packet.

Response Packet Structure

for messages which the container can send back to the server.

AJP13_SEND_BODY_CHUNK :=
  prefix_code   3
  chunk_length  (integer)
  chunk        *(byte)
  chunk_terminator (byte) Ox00

AJP13_SEND_HEADERS :=
  prefix_code       4
  http_status_code  (integer)
  http_status_msg   (string)
  num_headers       (integer)
  response_headers *(res_header_name header_value)

res_header_name :=
    sc_res_header_name | (string)   [see below for how this is parsed]

sc_res_header_name := 0xA0 (byte)

header_value := (string)

AJP13_END_RESPONSE :=
  prefix_code       5
  reuse             (boolean)

AJP13_GET_BODY_CHUNK :=
  prefix_code       6
  requested_length  (integer)

Details:

Send Body Chunk

The chunk is basically binary data, and is sent directly back to the browser.

Send Headers

The status code and message are the usual HTTP things (e.g. 200 and OK). The response header names are encoded the same way the request header names are. See header_encoding above for details about how the codes are distinguished from the strings.
The codes for common headers are:

Name | Code value
Content-Type | 0xA001
Content-Language | 0xA002
Content-Length | 0xA003
Date | 0xA004
Last-Modified | 0xA005
Location | 0xA006
Set-Cookie | 0xA007
Set-Cookie2 | 0xA008
Servlet-Engine | 0xA009
Status | 0xA00A
WWW-Authenticate | 0xA00B

After the code or the string header name, the header value is immediately encoded.

End Response

Signals the end of this request-handling cycle. If the reuse flag is true (anything other than 0 in the actual C code), this TCP connection can now be used to handle new incoming requests. If reuse is false (==0), the connection should be closed.

Get Body Chunk

The container asks for more data from the request (If the body was too large to fit in the first packet sent over or when the request is chunked). The server will send a body packet back with an amount of data which is the minimum of the request_length, the maximum send body size (8186 (8 Kbytes - 6)), and the number of bytes actually left to send from the request body.
If there is no more data in the body (i.e. the servlet container is trying to read past the end of the body), the server will send back an empty packet, which is a body packet with a payload length of 0. (0x12,0x34,0x00,0x00)


mod_proxy_balancer - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_balancer

Description: | mod_proxy extension for load balancing
Status: | Extension
Module Identifier: | proxy_balancer_module
Source File: | mod_proxy_balancer.c
Compatibility: | Available in version 2.1 and later

Summary

This module requires the service of mod_proxy and it provides load balancing for all the supported protocols. The most important ones are:

  • HTTP, using mod_proxy_http
  • FTP, using mod_proxy_ftp
  • AJP13, using mod_proxy_ajp
  • WebSocket, using mod_proxy_wstunnel

The Load balancing scheduler algorithm is not provided by this module but from other ones such as:

  • mod_lbmethod_byrequests
  • mod_lbmethod_bytraffic
  • mod_lbmethod_bybusyness
  • mod_lbmethod_heartbeat

Thus, in order to get the ability of load balancing, mod_proxy, mod_proxy_balancer and at least one of load balancing scheduler algorithm modules have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy

Load balancer scheduler algorithm

At present, there are 3 load balancer scheduler algorithms available for use: Request Counting, Weighted Traffic Counting and Pending Request Counting. These are controlled via the lbmethod value of the Balancer definition. See the ProxyPass directive for more information, especially regarding how to configure the Balancer and BalancerMembers.

Load balancer stickyness

The balancer supports stickyness. When a request is proxied to some back-end, then all following requests from the same user should be proxied to the same back-end. Many load balancers implement this feature via a table that maps client IP addresses to back-ends. This approach is transparent to clients and back-ends, but suffers from some problems: unequal load distribution if clients are themselves hidden behind proxies, stickyness errors when a client uses a dynamic IP address that changes during a session and loss of stickyness, if the mapping table overflows.

The module mod_proxy_balancer implements stickyness on top of two alternative means: cookies and URL encoding. Providing the cookie can be either done by the back-end or by the Apache web server itself. The URL encoding is usually done on the back-end.

Examples of a balancer configuration

Before we dive into the technical details, here's an example of how you might use mod_proxy_balancer to provide load balancing between two back-end servers:

<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80"
    BalancerMember "http://192.168.1.51:80"
</Proxy>
ProxyPass "/test" "balancer://mycluster"
ProxyPassReverse "/test" "balancer://mycluster"

Another example of how to provide load balancing with stickyness using mod_headers, even if the back-end server does not set a suitable session cookie:

Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80" route=1
    BalancerMember "http://192.168.1.51:80" route=2
    ProxySet stickysession=ROUTEID
</Proxy>
ProxyPass "/test" "balancer://mycluster"
ProxyPassReverse "/test" "balancer://mycluster"

Exported Environment Variables

At present there are 6 environment variables exported:

BALANCER_SESSION_STICKY

This is assigned the stickysession value used for the current request. It is the name of the cookie or request parameter used for sticky sessions

BALANCER_SESSION_ROUTE

This is assigned the route parsed from the current request.

BALANCER_NAME

This is assigned the name of the balancer used for the current request. The value is something like balancer://foo.

BALANCER_WORKER_NAME

This is assigned the name of the worker used for the current request. The value is something like http://hostA:1234.

BALANCER_WORKER_ROUTE

This is assigned the route of the worker that will be used for the current request.

BALANCER_ROUTE_CHANGED

This is set to 1 if the session route does not match the worker route (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) or the session does not yet have an established route. This can be used to determine when/if the client needs to be sent an updated route when sticky sessions are used.

Enabling Balancer Manager Support

This module requires the service of mod_status. Balancer manager enables dynamic update of balancer members. You can use balancer manager to change the balance factor of a particular member, or put it in the off line mode.

Thus, in order to get the ability of load balancer management, mod_status and mod_proxy_balancer have to be present in the server.

To enable load balancer management for browsers from the example.com domain add this code to your httpd.conf configuration file

<Location "/balancer-manager">
    SetHandler balancer-manager
    Require host example.com
</Location>

You can now access load balancer manager by using a Web browser to access the page http://your.server.name/balancer-manager. Please note that only Balancers defined outside of <Location ...> containers can be dynamically controlled by the Manager.

Details on load balancer stickyness

When using cookie based stickyness, you need to configure the name of the cookie that contains the information about which back-end to use. This is done via the stickysession attribute added to either ProxyPass or ProxySet. The name of the cookie is case-sensitive. The balancer extracts the value of the cookie and looks for a member worker with route equal to that value. The route must also be set in either ProxyPass or ProxySet. The cookie can either be set by the back-end, or as shown in the above example by the Apache web server itself.

Some back-ends use a slightly different form of stickyness cookie, for instance Apache Tomcat. Tomcat adds the name of the Tomcat instance to the end of its session id cookie, separated with a dot (.) from the session id. Thus if the Apache web server finds a dot in the value of the stickyness cookie, it only uses the part behind the dot to search for the route. In order to let Tomcat know about its instance name, you need to set the attribute jvmRoute inside the Tomcat configuration file conf/server.xml to the value of the route of the worker that connects to the respective Tomcat. The name of the session cookie used by Tomcat (and more generally by Java web applications based on servlets) is JSESSIONID (upper case) but can be configured to something else.

The second way of implementing stickyness is URL encoding. The web server searches for a query parameter in the URL of the request. The name of the parameter is specified again using stickysession. The value of the parameter is used to lookup a member worker with route equal to that value. Since it is not easy to extract and manipulate all URL links contained in responses, generally the work of adding the parameters to each link is done by the back-end generating the content. In some cases it might be feasible doing this via the web server using mod_substitute or mod_sed. This can have negative impact on performance though.

The Java standards implement URL encoding slightly different. They use a path info appended to the URL using a semicolon (;) as the separator and add the session id behind. As in the cookie case, Apache Tomcat can include the configured jvmRoute in this path info. To let Apache find this sort of path info, you neet to set scolonpathdelim to On in ProxyPass or ProxySet.

Finally you can support cookies and URL encoding at the same time, by configuring the name of the cookie and the name of the URL parameter separated by a vertical bar (|) as in the following example:

ProxyPass "/test" "balancer://mycluster" stickysession=JSESSIONID|jsessionid scolonpathdelim=On
<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80" route=node1
    BalancerMember "http://192.168.1.51:80" route=node2
</Proxy>

If the cookie and the request parameter both provide routing information for the same request, the information from the request parameter is used.

Troubleshooting load balancer stickyness

If you experience stickyness errors, e.g. users lose their application sessions and need to login again, you first want to check whether this is because the back-ends are sometimes unavailable or whether your configuration is wrong. To find out about possible stability problems with the back-ends, check your Apache error log for proxy error messages.

To verify your configuration, first check, whether the stickyness is based on a cookie or on URL encoding. Next step would be logging the appropriate data in the access log by using an enhanced LogFormat. The following fields are useful:

%{MYCOOKIE}C
The value contained in the cookie with name MYCOOKIE. The name should be the same given in the stickysession attribute.
%{Set-Cookie}o
This logs any cookie set by the back-end. You can track, whether the back-end sets the session cookie you expect, and to which value it is set.
%{BALANCER_SESSION_STICKY}e
The name of the cookie or request parameter used to lookup the routing information.
%{BALANCER_SESSION_ROUTE}e
The route information found in the request.
%{BALANCER_WORKER_ROUTE}e
The route of the worker chosen.
%{BALANCER_ROUTE_CHANGED}e
Set to 1 if the route in the request is different from the route of the worker, i.e. the request couldn't be handled sticky.

Common reasons for loss of session are session timeouts, which are usually configurable on the back-end server.

The balancer also logs detailed information about handling stickyness to the error log, if the log level is set to debug or higher. This is an easy way to troubleshoot stickyness problems, but the log volume might be to high for production servers under high load.


mod_proxy_connect - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_connect

Description: | mod_proxy extension for CONNECT request handling
Status: | Extension
Module Identifier: | proxy_connect_module
Source File: | mod_proxy_connect.c

Summary

This module requires the service of mod_proxy. It provides support for the CONNECT HTTP method. This method is mainly used to tunnel SSL requests through proxy servers.

Thus, in order to get the ability of handling CONNECT requests, mod_proxy and mod_proxy_connect have to be present in the server.

CONNECT is also used when the server needs to send an HTTPS request through a forward proxy. In this case the server acts as a CONNECT client. This functionality is part of mod_proxy and mod_proxy_connect is not needed in this case.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy

Request notes

mod_proxy_connect creates the following request notes for logging using the %{VARNAME}n format in LogFormat or ErrorLogFormat:

proxy-source-port
The local port used for the connection to the backend server.

AllowCONNECT Directive

Description: | Ports that are allowed to CONNECT through the proxy
Syntax: | AllowCONNECT port[-port] [port[-port]] ...
Default: | AllowCONNECT 443 563
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_connect
Compatibility: | Moved from mod_proxy in Apache 2.3.5. Port ranges available since Apache 2.3.7.

The AllowCONNECT directive specifies a list of port numbers or ranges to which the proxy CONNECT method may connect. Today's browsers use this method when a https connection is requested and proxy tunneling over HTTP is in effect.

By default, only the default https port (443) and the default snews port (563) are enabled. Use the AllowCONNECT directive to override this default and allow connections to the listed ports only.


mod_proxy_express - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_express

Description: | Dynamic mass reverse proxy extension for mod_proxy
Status: | Extension
Module Identifier: | proxy_express_module
Source File: | mod_proxy_express.c

Summary

This module creates dynamically configured mass reverse proxies, by mapping the Host: header of the HTTP request to a server name and backend URL stored in a DBM file. This allows for easy use of a huge number of reverse proxies with no configuration changes. It is much less feature-full than mod_proxy_balancer, which also provides dynamic growth, but is intended to handle much, much larger numbers of backends. It is ideally suited as a front-end HTTP switch.

This module requires the service of mod_proxy.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

Limitations

  • This module is not intended to replace the dynamic capability of mod_proxy_balancer. Instead, it is intended to be mostly a lightweight and fast alternative to using mod_rewrite with RewriteMap and the [P] flag for mapped reverse proxying.
  • It does not support regex or pattern matching at all.
  • It emulates:
    <VirtualHost *:80>
   ServerName front.end.server
   ProxyPass "/" "back.end.server:port"
   ProxyPassReverse "/" "back.end.server:port"
</VirtualHost>
    That is, the entire URL is appended to the mapped backend URL. This is in keeping with the intent of being a simple but fast reverse proxy switch.

See also

  • mod_proxy

ProxyExpressDBMFile Directive

Description: | Pathname to DBM file.
Syntax: | ProxyExpressDBMFile <pathname>
Default: | None
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_express
Compatibility: | Available in Apache 2.3.13 and later

The ProxyExpressDBMFile directive points to the location of the Express map DBM file. This file serves to map the incoming server name, obtained from the Host: header, to a backend URL.

Note

The file is constructed from a plain text file format using the httxt2dbm utility.

ProxyExpress map file

##
##express-map.txt:
##

www1.example.com http://192.168.211.2:8080
www2.example.com http://192.168.211.12:8088
www3.example.com http://192.168.212.10

Create DBM file

httxt2dbm -i express-map.txt -o emap

Configuration

ProxyExpressEnable on
ProxyExpressDBMFile emap

ProxyExpressDBMType Directive

Description: | DBM type of file.
Syntax: | ProxyExpressDBMFile <type>
Default: | "default"
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_express
Compatibility: | Available in Apache 2.3.13 and later

The ProxyExpressDBMType directive controls the DBM type expected by the module. The default is the default DBM type created with httxt2dbm.

Possible values are (not all may be available at run time):

Value | Description
db | Berkeley DB files
gdbm | GDBM files
ndbm | NDBM files
sdbm | SDBM files (always available)
default | default DBM type

ProxyExpressEnable Directive

Description: | Enable the module functionality.
Syntax: | ProxyExpressEnable [on|off]
Default: | off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_express
Compatibility: | Available in Apache 2.3.13 and later

The ProxyExpressEnable directive controls whether the module will be active.


mod_proxy_fcgi - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_fcgi

Description: | FastCGI support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_fcgi_module
Source File: | mod_proxy_fcgi.c
Compatibility: | Available in version 2.3 and later

Summary

This module requires the service of mod_proxy. It provides support for the FastCGI protocol.

Thus, in order to get the ability of handling the FastCGI protocol, mod_proxy and mod_proxy_fcgi have to be present in the server.

Unlike mod_fcgid and mod_fastcgi, mod_proxy_fcgi has no provision for starting the application process; fcgistarter is provided (on some platforms) for that purpose. Alternatively, external launching or process management may be available in the FastCGI application framework in use.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • fcgistarter
  • mod_proxy
  • mod_authnz_fcgi

Examples

Remember, in order to make the following examples work, you have to enable mod_proxy and mod_proxy_fcgi.

Single application instance

ProxyPass "/myapp/" "fcgi://localhost:4000/"

mod_proxy_fcgi disables connection reuse by default, so after a request has been completed the connection will NOT be held open by that httpd child process and won't be reused. If the FastCGI application is able to handle concurrent connections from httpd, you can opt-in to connection reuse as shown in the following example:

Single application instance, connection reuse (2.4.11 and later)

ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on

The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. The request URL is implicitly added to the 2nd parameter. The hostname and port following fcgi:// are where PHP-FPM is listening. Connection pooling is enabled.

PHP-FPM

ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on

The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. In this case, PHP-FPM is listening on a unix domain socket (UDS). Requires 2.4.9 or later. With this syntax, the hostname and optional port following fcgi:// are ignored.

PHP-FPM with UDS

      # UDS does not currently support connection reuse
      ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"

The balanced gateway needs mod_proxy_balancer and at least one load balancer algorithm module, such as mod_lbmethod_byrequests, in addition to the proxy modules listed above. mod_lbmethod_byrequests is the default, and will be used for this example configuration.

Balanced gateway to multiple application instances

ProxyPass "/myapp/" "balancer://myappcluster/"
<Proxy "balancer://myappcluster/">
    BalancerMember "fcgi://localhost:4000"
    BalancerMember "fcgi://localhost:4001"
</Proxy>

You can also force a request to be handled as a reverse-proxy request, by creating a suitable Handler pass-through. The example configuration below will pass all requests for PHP scripts to the specified FastCGI server using reverse proxy. This feature is available in Apache HTTP Server 2.4.10 and later. For performance reasons, you will want to define a worker representing the same fcgi:// backend. The benefit of this form is that it allows the normal mapping of URI to filename to occur in the server, and the local filesystem result is passed to the backend. When FastCGI is configured this way, the server can calculate the most accurate PATH_INFO.

Proxy via Handler

<FilesMatch "\.php$">
    # Note: The only part that varies is /path/to/app.sock
    SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
</FilesMatch>
   # Define a matching worker.
   # The part that is matched to the SetHandler is the part that
   # follows the pipe. If you need to distinguish, "localhost; can
   # be anything unique.
   <Proxy "fcgi://localhost/" enablereuse=on max=10>
   </Proxy>

<FilesMatch ...>
    SetHandler  "proxy:fcgi://localhost:9000"
</FilesMatch>

<FilesMatch ...>
    SetHandler  "proxy:balancer://myappcluster/"
</FilesMatch>

Environment Variables

In addition to the configuration directives that control the behaviour of mod_proxy, there are a number of environment variables that control the FCGI protocol provider:

proxy-fcgi-pathinfo
When configured via ProxyPass or ProxyPassMatch, mod_proxy_fcgi will not set the PATH_INFO environment variable. This allows the backend FCGI server to correctly determine SCRIPT_NAME and Script-URI and be compliant with RFC 3875 section 3.3. If instead you need mod_proxy_fcgi to generate a "best guess" for PATH_INFO, set this env-var. This is a workaround for a bug in some FCGI implementations. This variable can be set to multiple values to tweak at how the best guess is chosen (In 2.4.11 and later only):
first-dot
PATH_INFO is split from the slash following the first "." in the URL.
last-dot
PATH_INFO is split from the slash following the last "." in the URL.
full
PATH_INFO is calculated by an attempt to map the URL to the local filesystem.
unescape
PATH_INFO is the path component of the URL, unescaped / decoded.
any other value
PATH_INFO is the same as the path component of the URL. Originally, this was the only proxy-fcgi-pathinfo option.


mod_proxy_fdpass - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_fdpass

Description: | fdpass external process support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_fdpass_module
Source File: | mod_proxy_fdpass.c
Compatibility: | Available for unix in version 2.3 and later

Summary

This module requires the service of mod_proxy. It provides support for the passing the socket of the client to another process.

mod_proxy_fdpass uses the ability of AF_UNIX domain sockets to pass an open file descriptor to allow another process to finish handling a request.

The module has a proxy_fdpass_flusher provider interface, which allows another module to optionally send the response headers, or even the start of the response body. The default flush provider disables keep-alive, and sends the response headers, letting the external process just send a response body.

In order to use another provider, you have to set the flusher parameter in the ProxyPass directive.

At this time the only data passed to the external process is the client socket. To receive a client socket, call recvfrom with an allocated struct cmsghdr. Future versions of this module may include more data after the client socket, but this is not implemented at this time.

See also

  • mod_proxy


mod_proxy_ftp - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_ftp

Description: | FTP support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_ftp_module
Source File: | mod_proxy_ftp.c

Summary

This module requires the service of mod_proxy. It provides support for the proxying FTP sites. Note that FTP support is currently limited to the GET method.

Thus, in order to get the ability of handling FTP proxy requests, mod_proxy and mod_proxy_ftp have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy

Why doesn't file type xxx download via FTP?

You probably don't have that particular file type defined as application/octet-stream in your proxy's mime.types configuration file. A useful line can be

application/octet-stream   bin dms lha lzh exe class tgz taz

Alternatively you may prefer to default everything to binary:

ForceType application/octet-stream

How can I force an FTP ASCII download of File xxx?

In the rare situation where you must download a specific file using the FTP ASCII transfer method (while the default transfer is in binary mode), you can override mod_proxy's default by suffixing the request with ;type=a to force an ASCII transfer. (FTP Directory listings are always executed in ASCII mode, however.)

How can I do FTP upload?

Currently, only GET is supported for FTP in mod_proxy. You can of course use HTTP upload (POST or PUT) through an Apache proxy.

How can I access FTP files outside of my home directory?

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 a solution which is also used by other popular proxy servers like the Squid Proxy Cache. 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). For example, to retrieve the file /etc/motd, you would use the URL:

ftp://user@host/%2f/etc/motd

How can I hide the FTP cleartext password in my browser's URL line?

To log in to an FTP server by username and password, Apache uses different strategies. In absence of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e.,

user: anonymous
password: apache_proxy@

This works for all popular FTP servers which are configured for anonymous access.

For a personal login with a specific username, you can embed the user name into the URL, like in:

ftp://username@host/myfile

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

ftp://username:password@host/myfile

in the first place).

Note

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 insecure channels, an eavesdropper might intercept your password on its way.

Why do I get a file listing when I expected a file to be downloaded?

In order to allow both browsing the directories on an FTP server and downloading files, Apache looks at the request URL. If it looks like a directory, or contains wildcard characters ("*?[{~"), then it guesses that a listing is wanted instead of a download.

You can disable the special handling of names with wildcard characters. See the ProxyFtpListOnWildcard directive.

ProxyFtpDirCharset Directive

Description: | Define the character set for proxied FTP listings
Syntax: | ProxyFtpDirCharset character set
Default: | ProxyFtpDirCharset ISO-8859-1
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.2.7 and later. Moved from mod_proxy in Apache 2.3.5.

The ProxyFtpDirCharset directive defines the character set to be set for FTP directory listings in HTML generated by mod_proxy_ftp.

ProxyFtpEscapeWildcards Directive

Description: | Whether wildcards in requested filenames are escaped when sent to the FTP server
Syntax: | ProxyFtpEscapeWildcards [on|off]
Default: | on
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.3.3 and later

The ProxyFtpEscapeWildcards directive controls whether wildcard characters ("*?[{~") in requested filenames are escaped with backslash before sending them to the FTP server. That is the default behavior, but many FTP servers don't know about the escaping and try to serve the literal filenames they were sent, including the backslashes in the names.

Set to "off" to allow downloading files with wildcards in their names from FTP servers that don't understand wildcard escaping.

ProxyFtpListOnWildcard Directive

Description: | Whether wildcards in requested filenames trigger a file listing
Syntax: | ProxyFtpListOnWildcard [on|off]
Default: | on
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.3.3 and later

The ProxyFtpListOnWildcard directive controls whether wildcard characters ("*?[{~") in requested filenames cause mod_proxy_ftp to return a listing of files instead of downloading a file. By default (value on), they do. Set to "off" to allow downloading files even if they have wildcard characters in their names.


mod_proxy_html - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_html

Description: | Rewrite HTML links in to ensure they are addressable from Clients' networks in a proxy context.
Status: | Base
Module Identifier: | proxy_html_module
Source File: | mod_proxy_html.c
Compatibility: | Version 2.4 and later. Available as a third-party module for earlier 2.x versions

Summary

This module provides an output filter to rewrite HTML links in a proxy situation, to ensure that links work for users outside the proxy. It serves the same purpose as Apache's ProxyPassReverse directive does for HTTP headers, and is an essential component of a reverse proxy.

For example, if a company has an application server at appserver.example.com that is only visible from within the company's internal network, and a public webserver www.example.com, they may wish to provide a gateway to the application server at http://www.example.com/appserver/. When the application server links to itself, those links need to be rewritten to work through the gateway. mod_proxy_html serves to rewrite <a href="http://appserver.example.com/foo/bar.html">foobar</a> to <a href="http://www.example.com/appserver/foo/bar.html">foobar</a> making it accessible from outside.

mod_proxy_html was originally developed at WebŞing, whose extensive documentation may be useful to users.

ProxyHTMLBufSize Directive

Description: | Sets the buffer size increment for buffering inline scripts and stylesheets.
Syntax: | ProxyHTMLBufSize bytes
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

In order to parse non-HTML content (stylesheets and scripts) embedded in HTML documents, mod_proxy_html has to read the entire script or stylesheet into a buffer. This buffer will be expanded as necessary to hold the largest script or stylesheet in a page, in increments of bytes as set by this directive.

The default is 8192, and will work well for almost all pages. However, if you know you're proxying pages containing stylesheets and/or scripts bigger than 8K (that is, for a single script or stylesheet, NOT in total), it will be more efficient to set a larger buffer size and avoid the need to resize the buffer dynamically during a request.

ProxyHTMLCharsetOut Directive

Description: | Specify a charset for mod_proxy_html output.
Syntax: | ProxyHTMLCharsetOut Charset | *
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

This selects an encoding for mod_proxy_html output. It should not normally be used, as any change from the default UTF-8 (Unicode - as used internally by libxml2) will impose an additional processing overhead. The special token ProxyHTMLCharsetOut * will generate output using the same encoding as the input.

Note that this relies on mod_xml2enc being loaded.

ProxyHTMLDocType Directive

Description: Sets an HTML or XHTML document type declaration.
Syntax: ProxyHTMLDocType HTML|XHTML [Legacy]
OR
ProxyHTMLDocType fpi [SGML|XML]
Context: server config, virtual host, directory
Status: Base
Module: mod_proxy_html
Compatibility: Version 2.4 and later; available as a third-party for earlier 2.x versions

In the first form, documents will be declared as HTML 4.01 or XHTML 1.0 according to the option selected. This option also determines whether HTML or XHTML syntax is used for output. Note that the format of the documents coming from the backend server is immaterial: the parser will deal with it automatically. If the optional second argument is set to "Legacy", documents will be declared "Transitional", an option that may be necessary if you are proxying pre-1998 content or working with defective authoring/publishing tools.

In the second form, it will insert your own FPI. The optional second argument determines whether SGML/HTML or XML/XHTML syntax will be used.

The default is changed to omitting any FPI, on the grounds that no FPI is better than a bogus one. If your backend generates decent HTML or XHTML, set it accordingly.

If the first form is used, mod_proxy_html will also clean up the HTML to the specified standard. It cannot fix every error, but it will strip out bogus elements and attributes. It will also optionally log other errors at LogLevel Debug.

ProxyHTMLEnable Directive

Description: | Turns the proxy_html filter on or off.
Syntax: | ProxyHTMLEnable On|Off
Default: | ProxyHTMLEnable Off
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party module for earlier 2.x versions.

A simple switch to enable or disable the proxy_html filter. If mod_xml2enc is loaded it will also automatically set up internationalisation support.

Note that the proxy_html filter will only act on HTML data (Content-Type text/html or application/xhtml+xml) and when the data are proxied. You can override this (at your own risk) by setting the PROXY_HTML_FORCE environment variable.

ProxyHTMLEvents Directive

Description: | Specify attributes to treat as scripting events.
Syntax: | ProxyHTMLEvents attribute [attribute ...]
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

Specifies one or more attributes to treat as scripting events and apply ProxyHTMLURLMaps to where enabled. You can specify any number of attributes in one or more ProxyHTMLEvents directives.

Normally you'll set this globally. If you set ProxyHTMLEvents in more than one scope so that one overrides the other, you'll need to specify a complete set in each of those scopes.

A default configuration is supplied in proxy-html.conf and defines the events in standard HTML 4 and XHTML 1.

ProxyHTMLExtended Directive

Description: | Determines whether to fix links in inline scripts, stylesheets, and scripting events.
Syntax: | ProxyHTMLExtended On|Off
Default: | ProxyHTMLExtended Off
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

Set to Off, HTML links are rewritten according to the ProxyHTMLURLMap directives, but links appearing in Javascript and CSS are ignored.

Set to On, all scripting events (as determined by ProxyHTMLEvents) and embedded scripts or stylesheets are also processed by the ProxyHTMLURLMap rules, according to the flags set for each rule. Since this requires more parsing, performance will be best if you only enable it when strictly necessary.

You'll also need to take care over patterns matched, since the parser has no knowledge of what is a URL within an embedded script or stylesheet. In particular, extended matching of / is likely to lead to false matches.

ProxyHTMLFixups Directive

Description: | Fixes for simple HTML errors.
Syntax: | ProxyHTMLFixups [lowercase] [dospath] [reset]
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

This directive takes one to three arguments as follows:

  • lowercase Urls are rewritten to lowercase
  • dospath Backslashes in URLs are rewritten to forward slashes.
  • reset Unset any options set at a higher level in the configuration.

Take care when using these. The fixes will correct certain authoring mistakes, but risk also erroneously fixing links that were correct to start with. Only use them if you know you have a broken backend server.

ProxyHTMLInterp Directive

Description: | Enables per-request interpolation of ProxyHTMLURLMap rules.
Syntax: | ProxyHTMLInterp On|Off
Default: | ProxyHTMLInterp Off
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

This enables per-request interpolation in ProxyHTMLURLMap to- and from- patterns.

If interpolation is not enabled, all rules are pre-compiled at startup. With interpolation, they must be re-compiled for every request, which implies an extra processing overhead. It should therefore be enabled only when necessary.

ProxyHTMLLinks Directive

Description: | Specify HTML elements that have URL attributes to be rewritten.
Syntax: | ProxyHTMLLinks element attribute [attribute2 ...]
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

Specifies elements that have URL attributes that should be rewritten using standard ProxyHTMLURLMaps. You will need one ProxyHTMLLinks directive per element, but it can have any number of attributes.

Normally you'll set this globally. If you set ProxyHTMLLinks in more than one scope so that one overrides the other, you'll need to specify a complete set in each of those scopes.

A default configuration is supplied in proxy-html.conf and defines the HTML links for standard HTML 4 and XHTML 1.

ProxyHTMLMeta Directive

Description: | Turns on or off extra pre-parsing of metadata in HTML <head> sections.
Syntax: | ProxyHTMLMeta On|Off
Default: | ProxyHTMLMeta Off
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party module for earlier 2.x versions.

This turns on or off pre-parsing of metadata in HTML <head> sections.

If not required, turning ProxyHTMLMeta Off will give a small performance boost by skipping this parse step. However, it is sometimes necessary for internationalisation to work correctly.

ProxyHTMLMeta has two effects. Firstly and most importantly it enables detection of character encodings declared in the form

<meta http-equiv="Content-Type" content="text/html;charset=foo">

or, in the case of an XHTML document, an XML declaration. It is NOT required if the charset is declared in a real HTTP header (which is always preferable) from the backend server, nor if the document is utf-8 (unicode) or a subset such as ASCII. You may also be able to dispense with it where documents use a default declared using xml2EncDefault, but that risks propagating an incorrect declaration. A ProxyHTMLCharsetOut can remove that risk, but is likely to be a bigger processing overhead than enabling ProxyHTMLMeta.

The other effect of enabling ProxyHTMLMeta is to parse all <meta http-equiv=...> declarations and convert them to real HTTP headers, in keeping with the original purpose of this form of the HTML <meta> element.

ProxyHTMLStripComments Directive

Description: | Determines whether to strip HTML comments.
Syntax: | ProxyHTMLStripComments On|Off
Default: | ProxyHTMLStripComments Off
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party for earlier 2.x versions

This directive will cause mod_proxy_html to strip HTML comments. Note that this will also kill off any scripts or styles embedded in comments (a bogosity introduced in 1995/6 with Netscape 2 for the benefit of then-older browsers, but still in use today). It may also interfere with comment-based processors such as SSI or ESI: be sure to run any of those before mod_proxy_html in the filter chain if stripping comments!

ProxyHTMLURLMap Directive

Description: | Defines a rule to rewrite HTML links
Syntax: | ProxyHTMLURLMap from-pattern to-pattern [flags] [cond]
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_proxy_html
Compatibility: | Version 2.4 and later; available as a third-party module for earlier 2.x versions.

This is the key directive for rewriting HTML links. When parsing a document, whenever a link target matches from-pattern, the matching portion will be rewritten to to-pattern, as modified by any flags supplied and by the ProxyHTMLExtended directive.

The optional third argument may define any of the following Flags. Flags are case-sensitive.

h

Ignore HTML links (pass through unchanged)

e

Ignore scripting events (pass through unchanged)

c

Pass embedded script and style sections through untouched.

L

Last-match. If this rule matches, no more rules are applied (note that this happens automatically for HTML links).

l

Opposite to L. Overrides the one-change-only default behaviour with HTML links.

R

Use Regular Expression matching-and-replace. from-pattern is a regexp, and to-pattern a replacement string that may be based on the regexp. Regexp memory is supported: you can use brackets () in the from-pattern and retrieve the matches with $1 to $9 in the to-pattern.

If R is not set, it will use string-literal search-and-replace. The logic is starts-with in HTML links, but contains in scripting events and embedded script and style sections.

x

Use POSIX extended Regular Expressions. Only applicable with R.

i

Case-insensitive matching. Only applicable with R.

n

Disable regexp memory (for speed). Only applicable with R.

s

Line-based regexp matching. Only applicable with R.

^

Match at start only. This applies only to string matching (not regexps) and is irrelevant to HTML links.

$

Match at end only. This applies only to string matching (not regexps) and is irrelevant to HTML links.

V

Interpolate environment variables in to-pattern. A string of the form ${varname|default} will be replaced by the value of environment variable varname. If that is unset, it is replaced by default. The |default is optional.

NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.

v

Interpolate environment variables in from-pattern. Patterns supported are as above.

NOTE: interpolation will only be enabled if ProxyHTMLInterp is On.

The optional fourth cond argument defines a condition that will be evaluated per Request, provided ProxyHTMLInterp is On. If the condition evaluates FALSE the map will not be applied in this request. If TRUE, or if no condition is defined, the map is applied.

A cond is evaluated by the Expression Parser. In addition, the simpler syntax of conditions in mod_proxy_html 3.x for HTTPD 2.0 and 2.2 is also supported.


mod_proxy_http - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_http

Description: | HTTP support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_http_module
Source File: | mod_proxy_http.c

Summary

This module requires the service of mod_proxy. It provides the features used for proxying HTTP and HTTPS requests. mod_proxy_http supports HTTP/0.9, HTTP/1.0 and HTTP/1.1. It does not provide any caching abilities. If you want to set up a caching proxy, you might want to use the additional service of the mod_cache module.

Thus, in order to get the ability of handling HTTP proxy requests, mod_proxy and mod_proxy_http have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy
  • mod_proxy_connect

Environment Variables

In addition to the configuration directives that control the behaviour of mod_proxy, there are a number of environment variables that control the HTTP protocol provider. Environment variables below that don't specify specific values are enabled when set to any value.

proxy-sendextracrlf
Causes proxy to send an extra CR-LF newline on the end of a request. This is a workaround for a bug in some browsers.
force-proxy-request-1.0
Forces the proxy to send requests to the backend as HTTP/1.0 and disables HTTP/1.1 features.
proxy-nokeepalive
Forces the proxy to close the backend connection after each request.
proxy-chain-auth
If the proxy requires authentication, it will read and consume the proxy authentication credentials sent by the client. With proxy-chain-auth it will also forward the credentials to the next proxy in the chain. This may be necessary if you have a chain of proxies that share authentication information. Security Warning: Do not set this unless you know you need it, as it forwards sensitive information!
proxy-sendcl
HTTP/1.0 required all HTTP requests that include a body (e.g. POST requests) to include a Content-Length header. This environment variable forces the Apache proxy to send this header to the backend server, regardless of what the Client sent to the proxy. It ensures compatibility when proxying for an HTTP/1.0 or unknown backend. However, it may require the entire request to be buffered by the proxy, so it becomes very inefficient for large requests.
proxy-sendchunks or proxy-sendchunked
This is the opposite of proxy-sendcl. It allows request bodies to be sent to the backend using chunked transfer encoding. This allows the request to be efficiently streamed, but requires that the backend server supports HTTP/1.1.
proxy-interim-response
This variable takes values RFC (the default) or Suppress. Earlier httpd versions would suppress HTTP interim (1xx) responses sent from the backend. This is technically a violation of the HTTP protocol. In practice, if a backend sends an interim response, it may itself be extending the protocol in a manner we know nothing about, or just broken. So this is now configurable: set proxy-interim-response RFC to be fully protocol compliant, or proxy-interim-response Suppress to suppress interim responses.
proxy-initial-not-pooled
If this variable is set, no pooled connection will be reused if the client request is the initial request on the frontend connection. This avoids the "proxy: error reading status line from remote server" error message caused by the race condition that the backend server closed the pooled connection after the connection check by the proxy and before data sent by the proxy reached the backend. It has to be kept in mind that setting this variable downgrades performance, especially with HTTP/1.0 clients.

Request notes

mod_proxy_http creates the following request notes for logging using the %{VARNAME}n format in LogFormat or ErrorLogFormat:

proxy-source-port
The local port used for the connection to the backend server.
proxy-status
The HTTP status received from the backend server.


mod_proxy_scgi - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_scgi

Description: | SCGI gateway module for mod_proxy
Status: | Extension
Module Identifier: | proxy_scgi_module
Source File: | mod_proxy_scgi.c
Compatibility: | Available in version 2.2.14 and later

Summary

This module requires the service of mod_proxy. It provides support for the SCGI protocol, version 1.

Thus, in order to get the ability of handling the SCGI protocol, mod_proxy and mod_proxy_scgi have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy
  • mod_proxy_balancer

Examples

Remember, in order to make the following examples work, you have to enable mod_proxy and mod_proxy_scgi.

Simple gateway

ProxyPass /scgi-bin/ scgi://localhost:4000/

The balanced gateway needs mod_proxy_balancer and at least one load balancer algorithm module, such as mod_lbmethod_byrequests, in addition to the proxy modules listed above. mod_lbmethod_byrequests is the default, and will be used for this example configuration.

Balanced gateway

ProxyPass "/scgi-bin/" "balancer://somecluster/"
<Proxy "balancer://somecluster">
    BalancerMember "scgi://localhost:4000"
    BalancerMember "scgi://localhost:4001"
</Proxy>

Environment Variables

In addition to the configuration directives that control the behaviour of mod_proxy, an environment variable may also control the SCGI protocol provider:

proxy-scgi-pathinfo
By default mod_proxy_scgi will neither create nor export the PATH_INFO environment variable. This allows the backend SCGI server to correctly determine SCRIPT_NAME and Script-URI and be compliant with RFC 3875 section 3.3. If instead you need mod_proxy_scgi to generate a "best guess" for PATH_INFO, set this env-var. The variable must be set before SetEnv is effective. SetEnvIf can be used instead: SetEnvIf Request_URI . proxy-scgi-pathinfo

ProxySCGIInternalRedirect Directive

Description: | Enable or disable internal redirect responses from the backend
Syntax: | ProxySCGIInternalRedirect On|Off|Headername
Default: | ProxySCGIInternalRedirect On
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_scgi
Compatibility: | The Headername feature is available in version 2.4.13 and later

The ProxySCGIInternalRedirect enables the backend to internally redirect the gateway to a different URL. This feature originates in mod_cgi, which internally redirects the response if the response status is OK (200) and the response contains a Location (or configured alternate header) and its value starts with a slash (/). This value is interpreted as a new local URL that Apache httpd internally redirects to.

mod_proxy_scgi does the same as mod_cgi in this regard, except that you can turn off the feature or specify the use of a header other than Location.

Example

    ProxySCGIInternalRedirect Off

# Django and some other frameworks will fully qualify "local URLs"
# set by the application, so an alternate header must be used.
<Location /django-app/>
    ProxySCGIInternalRedirect X-Location
</Location>

ProxySCGISendfile Directive

Description: | Enable evaluation of X-Sendfile pseudo response header
Syntax: | ProxySCGISendfile On|Off|Headername
Default: | ProxySCGISendfile Off
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_scgi

The ProxySCGISendfile directive enables the SCGI backend to let files be served directly by the gateway. This is useful for performance purposes — httpd can use sendfile or other optimizations, which are not possible if the file comes over the backend socket. Additionally, the file contents are not transmitted twice.

The ProxySCGISendfile argument determines the gateway behaviour:

Off
No special handling takes place.
On
The gateway looks for a backend response header called X-Sendfile and interprets the value as the filename to serve. The header is removed from the final response headers. This is equivalent to ProxySCGISendfile X-Sendfile.
anything else
Similar to On, but instead of the hardcoded header name X-Sendfile, the argument is used as the header name.

Example

# Use the default header (X-Sendfile)
ProxySCGISendfile On

# Use a different header
ProxySCGISendfile X-Send-Static

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_proxy_wstunnel - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_wstunnel

Description: | Websockets support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_wstunnel_module
Source File: | mod_proxy_wstunnel.c
Compatibility: | Available in httpd 2.4.5 and later

Summary

This module requires the service of mod_proxy. It provides support for the tunnelling of web socket connections to a backend websockets server. The connection is automatically upgraded to a websocket connection:

HTTP Response

Upgrade: WebSocket
Connection: Upgrade

Proxying requests to a websockets server like echo.websocket.org can be done using the ProxyPass directive:

ProxyPass "/ws2/"  "ws://echo.websocket.org/"
ProxyPass "/wss2/" "wss://echo.websocket.org/"

Load balancing for multiple backends can be achieved using mod_proxy_balancer.

See also

  • mod_proxy


mod_ratelimit - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ratelimit

Description: | Bandwidth Rate Limiting for Clients
Status: | Extension
Module Identifier: | ratelimit_module
Source File: | mod_ratelimit.c

Summary

Provides a filter named RATE_LIMIT to limit client bandwidth. The connection speed to be simulated is specified, in KiB/s, using the environment variable rate-limit.

Example Configuration

<Location "/downloads">
    SetOutputFilter RATE_LIMIT
    SetEnv rate-limit 400
</Location>

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_reflector - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_reflector

Description: | Reflect a request body as a response via the output filter stack.
Status: | Base
Module Identifier: | reflector_module
Source File: | mod_reflector.c
Compatibility: | Version 2.3 and later

Summary

This module allows request bodies to be reflected back to the client, in the process passing the request through the output filter stack. A suitably configured chain of filters can be used to transform the request into a response. This module can be used to turn an output filter into an HTTP service.

Examples

Compression service
Pass the request body through the DEFLATE filter to compress the body. This request requires a Content-Encoding request header containing "gzip" for the filter to return compressed data.
<Location "/compress">
    SetHandler reflector
    SetOutputFilter DEFLATE
</Location>
Image downsampling service
Pass the request body through an image downsampling filter, and reflect the results to the caller.
<Location "/downsample">
    SetHandler reflector
    SetOutputFilter DOWNSAMPLE
</Location>

ReflectorHeader Directive

Description: | Reflect an input header to the output headers
Syntax: | ReflectorHeader inputheader [outputheader]
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_reflector

This directive controls the reflection of request headers to the response. The first argument is the name of the request header to copy. If the optional second argument is specified, it will be used as the name of the response header, otherwise the original request header name will be used.


mod_remoteip - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_remoteip

Description: | Replaces the original client IP address for the connection with the useragent IP address list presented by a proxies or a load balancer via the request headers.
Status: | Base
Module Identifier: | remoteip_module
Source File: | mod_remoteip.c

Summary

This module is used to treat the useragent which initiated the request as the originating useragent as identified by httpd for the purposes of authorization and logging, even where that useragent is behind a load balancer, front end server, or proxy server.

The module overrides the client IP address for the connection with the useragent IP address reported in the request header configured with the RemoteIPHeader directive.

Once replaced as instructed, this overridden useragent IP address is then used for the mod_authz_host Require ip feature, is reported by mod_status, and is recorded by mod_log_config %a and core %a format strings. The underlying client IP of the connection is available in the %{c}a format string.

It is critical to only enable this behavior from intermediate hosts (proxies, etc) which are trusted by this server, since it is trivial for the remote useragent to impersonate another useragent.

See also

  • mod_authz_host
  • mod_status
  • mod_log_config

Remote IP Processing

Apache by default identifies the useragent with the connection's client_ip value, and the connection remote_host and remote_logname are derived from this value. These fields play a role in authentication, authorization and logging and other purposes by other loadable modules.

mod_remoteip overrides the client IP of the connection with the advertised useragent IP as provided by a proxy or load balancer, for the duration of the request. A load balancer might establish a long lived keepalive connection with the server, and each request will have the correct useragent IP, even though the underlying client IP address of the load balancer remains unchanged.

When multiple, comma delimited useragent IP addresses are listed in the header value, they are processed in Right-to-Left order. Processing halts when a given useragent IP address is not trusted to present the preceding IP address. The header field is updated to this remaining list of unconfirmed IP addresses, or if all IP addresses were trusted, this header is removed from the request altogether.

In overriding the client IP, the module stores the list of intermediate hosts in a remoteip-proxy-ip-list note, which mod_log_config can record using the %{remoteip-proxy-ip-list}n format token. If the administrator needs to store this as an additional header, this same value can also be recording as a header using the directive RemoteIPProxiesHeader.

IPv4-over-IPv6 Mapped Addresses

As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded in their IPv4 representation.

Internal (Private) Addresses

All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8 blocks (and IPv6 addresses outside of the public 2000::/3 block) are only evaluated by mod_remoteip when RemoteIPInternalProxy internal (intranet) proxies are registered.

RemoteIPHeader Directive

Description: | Declare the header field which should be parsed for useragent IP addresses
Syntax: | RemoteIPHeader header-field
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPHeader directive triggers mod_remoteip to treat the value of the specified header-field header as the useragent IP address, or list of intermediate useragent IP addresses, subject to further configuration of the RemoteIPInternalProxy and RemoteIPTrustedProxy directives. Unless these other directives are used, mod_remoteip will trust all hosts presenting a RemoteIPHeader IP value.

Internal (Load Balancer) Example

RemoteIPHeader X-Client-IP

Proxy Example

RemoteIPHeader X-Forwarded-For

RemoteIPInternalProxy Directive

Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax: | RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ...
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPInternalProxy directive adds one or more addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP. Unlike the RemoteIPTrustedProxy directive, any IP address presented in this header, including private intranet addresses, are trusted when passed from these proxies.

Internal (Load Balancer) Example

RemoteIPHeader X-Client-IP
RemoteIPInternalProxy 10.0.2.0/24
RemoteIPInternalProxy gateway.localdomain

RemoteIPInternalProxyList Directive

Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax: | RemoteIPInternalProxyList filename
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPInternalProxyList directive specifies a file parsed at startup, and builds a list of addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP.

The '#' hash character designates a comment line, otherwise each whitespace or newline separated entry is processed identically to the RemoteIPInternalProxy directive.

Internal (Load Balancer) Example

RemoteIPHeader X-Client-IP
RemoteIPInternalProxyList conf/trusted-proxies.lst

conf/trusted-proxies.lst contents

# Our internally trusted proxies;
10.0.2.0/24         #Everyone in the testing group
gateway.localdomain #The front end balancer

RemoteIPProxiesHeader Directive

Description: | Declare the header field which will record all intermediate IP addresses
Syntax: | RemoteIPProxiesHeader HeaderFieldName
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPProxiesHeader directive specifies a header into which mod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the useragent IP of the request. Note that intermediate RemoteIPTrustedProxy addresses are recorded in this header, while any intermediate RemoteIPInternalProxy addresses are discarded.

Example

RemoteIPHeader X-Forwarded-For
RemoteIPProxiesHeader X-Forwarded-By

RemoteIPTrustedProxy Directive

Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax: | RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ...
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPTrustedProxy directive adds one or more addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP. Unlike the RemoteIPInternalProxy directive, any intranet or private IP address reported by such proxies, including the 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public 2000::/3 block) are not trusted as the useragent IP, and are left in the RemoteIPHeader header's value.

Trusted (Load Balancer) Example

RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxy 10.0.2.16/28
RemoteIPTrustedProxy proxy.example.com

RemoteIPTrustedProxyList Directive

Description: | Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax: | RemoteIPTrustedProxyList filename
Context: | server config, virtual host
Status: | Base
Module: | mod_remoteip

The RemoteIPTrustedProxyList directive specifies a file parsed at startup, and builds a list of addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP.

The '#' hash character designates a comment line, otherwise each whitespace or newline separated entry is processed identically to the RemoteIPTrustedProxy directive.

Trusted (Load Balancer) Example

RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxyList conf/trusted-proxies.lst

conf/trusted-proxies.lst contents

# Identified external proxies;
192.0.2.16/28 #wap phone group of proxies
proxy.isp.example.com #some well known ISP


mod_reqtimeout - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_reqtimeout

Description: | Set timeout and minimum data rate for receiving requests
Status: | Extension
Module Identifier: | reqtimeout_module
Source File: | mod_reqtimeout.c
Compatibility: | Available in Apache HTTPD 2.2.15 and later

Examples

  1. Allow 10 seconds to receive the request including the headers and 30 seconds for receiving the request body:
    RequestReadTimeout header=10 body=30
  2. Allow at least 10 seconds to receive the request body. If the client sends data, increase the timeout by 1 second for every 1000 bytes received, with no upper limit for the timeout (except for the limit given indirectly by LimitRequestBody):
    RequestReadTimeout body=10,MinRate=1000
  3. Allow at least 10 seconds to receive the request including the headers. If the client sends data, increase the timeout by 1 second for every 500 bytes received. But do not allow more than 30 seconds for the request including the headers:
    RequestReadTimeout header=10-30,MinRate=500
  4. Usually, a server should have both header and body timeouts configured. If a common configuration is used for http and https virtual hosts, the timeouts should not be set too low:
    RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500

RequestReadTimeout Directive

Description: | Set timeout values for receiving request headers and body from client.
Syntax: | RequestReadTimeout [header=timeout[-maxtimeout][,MinRate=rate] [body=timeout[-maxtimeout][,MinRate=rate]
Default: | header=20-40,MinRate=500 body=20,MinRate=500
Context: | server config, virtual host
Status: | Extension
Module: | mod_reqtimeout
Compatibility: | Available in version 2.2.15 and later; defaulted to disabled in version 2.3.14 and earlier.

This directive can set various timeouts for receiving the request headers and the request body from the client. If the client fails to send headers or body within the configured time, a 408 REQUEST TIME OUT error is sent.

For SSL virtual hosts, the header timeout values include the time needed to do the initial SSL handshake. If the user's browser is configured to query certificate revocation lists and the CRL server is not reachable, the initial SSL handshake may take a significant time until the browser gives up waiting for the CRL. Therefore the header timeout values should not be set to very low values for SSL virtual hosts. The body timeout values include the time needed for SSL renegotiation (if necessary).

When an AcceptFilter is in use (usually the case on Linux and FreeBSD), the socket is not sent to the server process before at least one byte (or the whole request for httpready) is received. The header timeout configured with RequestReadTimeout is only effective after the server process has received the socket.

For each of the two timeout types (header or body), there are three ways to specify the timeout:

  • Fixed timeout value:

    type=timeout

    The time in seconds allowed for reading all of the request headers or body, respectively. A value of 0 means no limit.

  • Disable module for a vhost::

    header=0 body=0

    This disables mod_reqtimeout completely.

  • Timeout value that is increased when data is received:

    type=timeout,MinRate=data_rate

    Same as above, but whenever data is received, the timeout value is increased according to the specified minimum data rate (in bytes per second).

  • Timeout value that is increased when data is received, with an upper bound:

    type=timeout-maxtimeout,MinRate=data_rate

    Same as above, but the timeout will not be increased above the second value of the specified timeout range.


mod_request - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_request

Açıklama: | HTTP istek gövdelerini işleme sokup kullanılabilir kılan süzgeçler
Durum: | Temel
Modül Betimleyici: | request_module
Kaynak Dosyası: | mod_request.c
Uyumluluk: | Apache 2.3 ve sonrasında mevcuttur.

KeptBodySize Yönergesi

Açıklama: | mod_include gibi süzgeçler tarafından kullanılma olasılığına karşı istek gövdesi iptal edilmek yerine belirtilen azami boyutta tutulur.
Sözdizimi: | KeptBodySize azami_bayt_sayısı
Öntanımlı: | KeptBodySize 0
Bağlam: | dizin
Durum: | Temel
Modül: | mod_request

Normal şartlar altında, durağan dosyaların öntanımlı eylemcileri gibi istek eylemcileri gerek kalmadığında istek gövdesini iptal ederler. Sonuç olarak, mod_include gibi süzgeçler, özgün istek (süzme işlemi gerçekleştikten sonra artık gerekmediğinden istek gövdesini iptal eden) bir POST isteği olsa bile, GET isteklerinin yapılmasına sadece diğer URL’lerin alt istekler olarak içerilmesi şartıyla izin verir.

Bu yönergede belirtilen değer sıfırdan büyük olduğunda, istek eylemciler, istek gövdesini iptal etmek yerine süzgeçler tarafından kullanılmak üzere belirtilen azami boyuta ayarlarlar. mod_include süzgecinin kullanılması durumunda, bir durağan shtml dosyası için bir POST isteği, ardından gelen isteklerin, önceki gibi GET istekleri değil, POST istekleri olmasına yol açacaktır.

Bu özellik, mod_include kullanılarak, karmaşık HTML sayfalarının ve uygulamalarının küçük küçük bileşenlere bölünüp sonra da sayfa yapısıyla birlikte sarmalanarak birleştirilmesini mümkün kılar. Bileşenler, CGI programları veya betik dilleri biçiminde olabileceği gibi, mod_proxy kullanarak başka bir sunucudaki URL uzayına ters vekil URL’ler şeklinde bile olabilir.

Bilginize: İstekler tamamlanana kadar alınan istekler geçici RAM içinde biriktirilir. Sonuç olarak, bahsi geçen yükü karşılamak için yeterince RAM’in mevcut olması gerekir. Bu yönergeyi kullanmakla, istek gövdesini saklamaya yetecek olası en düşük değerle bile URL uzayınız için gereken yeri kısıtlamış olursunuz.

Eğer isteğin uzunluğu bu yönerge ile ayrılan azami uzunluğu aşarsa sunucu yanıt olarak 413 Request Entity Too Large (413 İstenen Öğe Çok Büyük) hatasını döndürür.

İstek gövdesini iptal etmek yerine kendi amaçları doğrultusunda bunları biriktiren mod_cgi gibi eylemciler bu yönergeyi dikkate almazlar.

Ayrıca bakınız:

  • mod_include belgesi
  • mod_auth_form belgesi

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_sed - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_sed

Description: | Filter Input (request) and Output (response) content using sed syntax
Status: | Experimental
Module Identifier: | sed_module
Source File: | mod_sed.c sed0.c sed1.c regexp.c regexp.h sed.h
Compatibility: | Available in Apache 2.3 and later

Summary

mod_sed is an in-process content filter. The mod_sed filter implements the sed editing commands implemented by the Solaris 10 sed program as described in the manual page. However, unlike sed, mod_sed doesn't take data from standard input. Instead, the filter acts on the entity data sent between client and server. mod_sed can be used as an input or output filter. mod_sed is a content filter, which means that it cannot be used to modify client or server http headers.

The mod_sed output filter accepts a chunk of data, executes the sed scripts on the data, and generates the output which is passed to the next filter in the chain.

The mod_sed input filter reads the data from the next filter in the chain, executes the sed scripts, and returns the generated data to the caller filter in the filter chain.

Both the input and output filters only process the data if newline characters are seen in the content. At the end of the data, the rest of the data is treated as the last line.

A tutorial article on mod_sed, and why it is more powerful than simple string or regular expression search and replace, is available on the author's blog.

Sample Configuration

Adding an output filter

# In the following example, the sed filter will change the string
# "monday" to "MON" and the string "sunday" to SUN in html documents
# before sending to the client.
<Directory "/var/www/docs/sed">
    AddOutputFilter Sed html
    OutputSed "s/monday/MON/g"
    OutputSed "s/sunday/SUN/g"
</Directory>

Adding an input filter

# In the following example, the sed filter will change the string
# "monday" to "MON" and the string "sunday" to SUN in the POST data
# sent to PHP.
<Directory "/var/www/docs/sed">
    AddInputFilter Sed php
    InputSed "s/monday/MON/g"
    InputSed "s/sunday/SUN/g"
</Directory>

Sed Commands

Complete details of the sed command can be found from the sed manual page.

b
Branch to the label specified (similar to goto).
h
Copy the current line to the hold buffer.
H
Append the current line to the hold buffer.
g
Copy the hold buffer to the current line.
G
Append the hold buffer to the current line.
x
Swap the contents of the hold buffer and the current line.

InputSed Directive

Description: | Sed command to filter request data (typically POST data)
Syntax: | InputSed sed-command
Context: | directory, .htaccess
Status: | Experimental
Module: | mod_sed

The InputSed directive specifies the sed command to execute on the request data e.g., POST data.

OutputSed Directive

Description: | Sed command for filtering response content
Syntax: | OutputSed sed-command
Context: | directory, .htaccess
Status: | Experimental
Module: | mod_sed

The OutputSed directive specifies the sed command to execute on the response.


mod_session - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_session

Description: | Session support
Status: | Extension
Module Identifier: | session_module
Source File: | mod_session.c
Compatibility: | Available in Apache 2.3 and later

Summary

Warning

The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This module provides support for a server wide per user session interface. Sessions can be used for keeping track of whether a user has been logged in, or for other per user information that should be kept available across requests.

Sessions may be stored on the server, or may be stored on the browser. Sessions may also be optionally encrypted for added security. These features are divided into several modules in addition to mod_session; mod_session_crypto, mod_session_cookie and mod_session_dbd. Depending on the server requirements, load the appropriate modules into the server (either statically at compile time or dynamically via the LoadModule directive).

Sessions may be manipulated from other modules that depend on the session, or the session may be read from and written to using environment variables and HTTP headers, as appropriate.

See also

  • mod_session_cookie
  • mod_session_crypto
  • mod_session_dbd

What is a session?

At the core of the session interface is a table of key and value pairs that are made accessible across browser requests. These pairs can be set to any valid string, as needed by the application making use of the session.

The "session" is a application/x-www-form-urlencoded string containing these key value pairs, as defined by the HTML specification.

The session can optionally be encrypted and base64 encoded before being written to the storage mechanism, as defined by the administrator.

Who can use a session?

The session interface is primarily developed for the use by other server modules, such as mod_auth_form, however CGI based applications can optionally be granted access to the contents of the session via the HTTP_SESSION environment variable. Sessions have the option to be modified and/or updated by inserting an HTTP response header containing the new session parameters.

Keeping sessions on the server

Apache can be configured to keep track of per user sessions stored on a particular server or group of servers. This functionality is similar to the sessions available in typical application servers.

If configured, sessions are tracked through the use of a session ID that is stored inside a cookie, or extracted from the parameters embedded within the URL query string, as found in a typical GET request.

As the contents of the session are stored exclusively on the server, there is an expectation of privacy of the contents of the session. This does have performance and resource implications should a large number of sessions be present, or where a large number of webservers have to share sessions with one another.

The mod_session_dbd module allows the storage of user sessions within a SQL database via mod_dbd.

Keeping sessions on the browser

In high traffic environments where keeping track of a session on a server is too resource intensive or inconvenient, the option exists to store the contents of the session within a cookie on the client browser instead.

This has the advantage that minimal resources are required on the server to keep track of sessions, and multiple servers within a server farm have no need to share session information.

The contents of the session however are exposed to the client, with a corresponding risk of a loss of privacy. The mod_session_crypto module can be configured to encrypt the contents of the session before writing the session to the client.

The mod_session_cookie allows the storage of user sessions on the browser within an HTTP cookie.

Basic Examples

Creating a session is as simple as turning the session on, and deciding where the session will be stored. In this example, the session will be stored on the browser, in a cookie called session.

Browser based session

Session On
SessionCookieName session path=/

The session is not useful unless it can be written to or read from. The following example shows how values can be injected into the session through the use of a predetermined HTTP response header called X-Replace-Session.

Writing to a session

Session On
SessionCookieName session path=/
SessionHeader X-Replace-Session

The header should contain name value pairs expressed in the same format as a query string in a URL, as in the example below. Setting a key to the empty string has the effect of removing that key from the session.

CGI to write to a session

#!/bin/bash
echo "Content-Type: text/plain"
echo "X-Replace-Session: key1=foo&key2=&key3=bar"
echo
env

If configured, the session can be read back from the HTTP_SESSION environment variable. By default, the session is kept private, so this has to be explicitly turned on with the SessionEnv directive.

Read from a session

Session On
SessionEnv On
SessionCookieName session path=/
SessionHeader X-Replace-Session

Once read, the CGI variable HTTP_SESSION should contain the value key1=foo&key3=bar.

Session Privacy

Using the "show cookies" feature of your browser, you would have seen a clear text representation of the session. This could potentially be a problem should the end user need to be kept unaware of the contents of the session, or where a third party could gain unauthorised access to the data within the session.

The contents of the session can be optionally encrypted before being placed on the browser using the mod_session_crypto module.

Browser based encrypted session

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/

The session will be automatically decrypted on load, and encrypted on save by Apache, the underlying application using the session need have no knowledge that encryption is taking place.

Sessions stored on the server rather than on the browser can also be encrypted as needed, offering privacy where potentially sensitive information is being shared between webservers in a server farm using the mod_session_dbd module.

Cookie Privacy

The HTTP cookie mechanism also offers privacy features, such as the ability to restrict cookie transport to SSL protected pages only, or to prevent browser based javascript from gaining access to the contents of the cookie.

Warning

Some of the HTTP cookie privacy features are either non-standard, or are not implemented consistently across browsers. The session modules allow you to set cookie parameters, but it makes no guarantee that privacy will be respected by the browser. If security is a concern, use the mod_session_crypto to encrypt the contents of the session, or store the session on the server using the mod_session_dbd module.

Standard cookie parameters can be specified after the name of the cookie, as in the example below.

Setting cookie parameters

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/private;domain=example.com;httponly;secure;

In cases where the Apache server forms the frontend for backend origin servers, it is possible to have the session cookies removed from the incoming HTTP headers using the SessionCookieRemove directive. This keeps the contents of the session cookies from becoming accessible from the backend server.

Session Support for Authentication

As is possible within many application servers, authentication modules can use a session for storing the username and password after login. The mod_auth_form saves the user's login name and password within the session.

Form based authentication

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/
AuthFormProvider file
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
#...

See the mod_auth_form module for documentation and complete examples.

Integrating Sessions with External Applications

In order for sessions to be useful, it must be possible to share the contents of a session with external applications, and it must be possible for an external application to write a session of its own.

A typical example might be an application that changes a user's password set by mod_auth_form. This application would need to read the current username and password from the session, make the required changes to the user's password, and then write the new password to the session in order to provide a seamless transition to the new password.

A second example might involve an application that registers a new user for the first time. When registration is complete, the username and password is written to the session, providing a seamless transition to being logged in.

Apache modules
Modules within the server that need access to the session can use the mod_session.h API in order to read from and write to the session. This mechanism is used by modules like mod_auth_form.
CGI programs and scripting languages
Applications that run within the webserver can optionally retrieve the value of the session from the HTTP_SESSION environment variable. The session should be encoded as a application/x-www-form-urlencoded string as described by the HTML specification. The environment variable is controlled by the setting of the SessionEnv directive. The session can be written to by the script by returning a application/x-www-form-urlencoded response header with a name set by the SessionHeader directive. In both cases, any encryption or decryption, and the reading the session from or writing the session to the chosen storage mechanism is handled by the mod_session modules and corresponding configuration.
Applications behind mod_proxy
If the SessionHeader directive is used to define an HTTP request header, the session, encoded as a application/x-www-form-urlencoded string, will be made available to the application. If the same header is provided in the response, the value of this response header will be used to replace the session. As above, any encryption or decryption, and the reading the session from or writing the session to the chosen storage mechanism is handled by the mod_session modules and corresponding configuration.
Standalone applications
Applications might choose to manipulate the session outside the control of the Apache HTTP server. In this case, it is the responsibility of the application to read the session from the chosen storage mechanism, decrypt the session, update the session, encrypt the session and write the session to the chosen storage mechanism, as appropriate.

Session Directive

Description: | Enables a session for the current directory or location
Syntax: | Session On|Off
Default: | Session Off
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_session

The Session directive enables a session for the directory or location container. Further directives control where the session will be stored and how privacy is maintained.

SessionEnv Directive

Description: | Control whether the contents of the session are written to the HTTP_SESSION environment variable
Syntax: | SessionEnv On|Off
Default: | SessionEnv Off
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_session

If set to On, the SessionEnv directive causes the contents of the session to be written to a CGI environment variable called HTTP_SESSION.

The string is written in the URL query format, for example:

key1=foo&key3=bar

SessionExclude Directive

Description: | Define URL prefixes for which a session is ignored
Syntax: | SessionExclude path
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session

The SessionExclude directive allows sessions to be disabled relative to URL prefixes only. This can be used to make a website more efficient, by targeting a more precise URL space for which a session should be maintained. By default, all URLs within the directory or location are included in the session. The SessionExclude directive takes precedence over the SessionInclude directive.

Warning

This directive has a similar purpose to the path attribute in HTTP cookies, but should not be confused with this attribute. This directive does not set the path attribute, which must be configured separately.

SessionHeader Directive

Description: | Import session updates from a given HTTP response header
Syntax: | SessionHeader header
Default: | none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_session

The SessionHeader directive defines the name of an HTTP response header which, if present, will be parsed and written to the current session.

The header value is expected to be in the URL query format, for example:

key1=foo&key2=&key3=bar

Where a key is set to the empty string, that key will be removed from the session.

SessionInclude Directive

Description: | Define URL prefixes for which a session is valid
Syntax: | SessionInclude path
Default: | all URLs
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_session

The SessionInclude directive allows sessions to be made valid for specific URL prefixes only. This can be used to make a website more efficient, by targeting a more precise URL space for which a session should be maintained. By default, all URLs within the directory or location are included in the session.

Warning

This directive has a similar purpose to the path attribute in HTTP cookies, but should not be confused with this attribute. This directive does not set the path attribute, which must be configured separately.

SessionMaxAge Directive

Description: | Define a maximum age in seconds for a session
Syntax: | SessionMaxAge maxage
Default: | SessionMaxAge 0
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_session

The SessionMaxAge directive defines a time limit for which a session will remain valid. When a session is saved, this time limit is reset and an existing session can be continued. If a session becomes older than this limit without a request to the server to refresh the session, the session will time out and be removed. Where a session is used to stored user login details, this has the effect of logging the user out automatically after the given time.

Setting the maxage to zero disables session expiry.


mod_session_cookie - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_session_cookie

Description: | Cookie based session support
Status: | Extension
Module Identifier: | session_cookie_module
Source File: | mod_session_cookie.c
Compatibility: | Available in Apache 2.3 and later

Summary

Warning

The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This submodule of mod_session provides support for the storage of user sessions on the remote browser within HTTP cookies.

Using cookies to store a session removes the need for the server or a group of servers to store the session locally, or collaborate to share a session, and can be useful for high traffic environments where a server based session might be too resource intensive.

If session privacy is required, the mod_session_crypto module can be used to encrypt the contents of the session before writing the session to the client.

For more details on the session interface, see the documentation for the mod_session module.

See also

  • mod_session
  • mod_session_crypto
  • mod_session_dbd

Basic Examples

To create a simple session and store it in a cookie called session, configure the session as follows:

Browser based session

Session On
SessionCookieName session path=/

For more examples on how the session can be configured to be read from and written to by a CGI application, see the mod_session examples section.

For documentation on how the session can be used to store username and password details, see the mod_auth_form module.

SessionCookieName Directive

Description: | Name and attributes for the RFC2109 cookie storing the session
Syntax: | SessionCookieName name attributes
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_cookie

The SessionCookieName directive specifies the name and optional attributes of an RFC2109 compliant cookie inside which the session will be stored. RFC2109 cookies are set using the Set-Cookie HTTP header.

An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification.

Cookie with attributes

Session On
SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1;

SessionCookieName2 Directive

Description: | Name and attributes for the RFC2965 cookie storing the session
Syntax: | SessionCookieName2 name attributes
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_cookie

The SessionCookieName2 directive specifies the name and optional attributes of an RFC2965 compliant cookie inside which the session will be stored. RFC2965 cookies are set using the Set-Cookie2 HTTP header.

An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification.

Cookie2 with attributes

Session On
SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;

SessionCookieRemove Directive

Description: | Control for whether session cookies should be removed from incoming HTTP headers
Syntax: | SessionCookieRemove On|Off
Default: | SessionCookieRemove Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_cookie

The SessionCookieRemove flag controls whether the cookies containing the session will be removed from the headers during request processing.

In a reverse proxy situation where the Apache server acts as a server frontend for a backend origin server, revealing the contents of the session cookie to the backend could be a potential privacy violation. When set to on, the session cookie will be removed from the incoming HTTP headers.


mod_session_crypto - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_session_crypto

Description: | Session encryption support
Status: | Experimental
Module Identifier: | session_crypto_module
Source File: | mod_session_crypto.c
Compatibility: | Available in Apache 2.3 and later

Summary

Warning

The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This submodule of mod_session provides support for the encryption of user sessions before being written to a local database, or written to a remote browser via an HTTP cookie.

This can help provide privacy to user sessions where the contents of the session should be kept private from the user, or where protection is needed against the effects of cross site scripting attacks.

For more details on the session interface, see the documentation for the mod_session module.

See also

  • mod_session
  • mod_session_cookie
  • mod_session_dbd

Basic Usage

To create a simple encrypted session and store it in a cookie called session, configure the session as follows:

Browser based encrypted session

Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

The session will be encrypted with the given key. Different servers can be configured to share sessions by ensuring the same encryption key is used on each server.

If the encryption key is changed, sessions will be invalidated automatically.

For documentation on how the session can be used to store username and password details, see the mod_auth_form module.

SessionCryptoCipher Directive

Description: | The crypto cipher to be used to encrypt the session
Syntax: | SessionCryptoCipher name
Default: | aes256
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The SessionCryptoCipher directive allows the cipher to be used during encryption. If not specified, the cipher defaults to aes256.

Possible values depend on the crypto driver in use, and could be one of:

  • 3des192
  • aes128
  • aes192
  • aes256

SessionCryptoDriver Directive

Description: | The crypto driver to be used to encrypt the session
Syntax: | SessionCryptoDriver name [param[=value]]
Default: | none
Context: | server config
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The SessionCryptoDriver directive specifies the name of the crypto driver to be used for encryption. If not specified, the driver defaults to the recommended driver compiled into APR-util.

The NSS crypto driver requires some parameters for configuration, which are specified as parameters with optional values after the driver name.

NSS without a certificate database

SessionCryptoDriver nss

NSS with certificate database

SessionCryptoDriver nss dir=certs

NSS with certificate database and parameters

SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod

NSS with paths containing spaces

SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod

The NSS crypto driver might have already been configured by another part of the server, for example from mod_nss or mod_ldap. If found to have already been configured, a warning will be logged, and the existing configuration will have taken affect. To avoid this warning, use the noinit parameter as follows.

NSS with certificate database

SessionCryptoDriver nss noinit

To prevent confusion, ensure that all modules requiring NSS are configured with identical parameters.

The openssl crypto driver supports an optional parameter to specify the engine to be used for encryption.

OpenSSL with engine support

SessionCryptoDriver openssl engine=name

SessionCryptoPassphrase Directive

Description: | The key used to encrypt the session
Syntax: | SessionCryptoPassphrase secret [ secret ... ]
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The SessionCryptoPassphrase directive specifies the keys to be used to enable symmetrical encryption on the contents of the session before writing the session, or decrypting the contents of the session after reading the session.

Keys are more secure when they are long, and consist of truly random characters. Changing the key on a server has the effect of invalidating all existing sessions.

Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list.

As of version 2.4.7 if the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the key.

#key used as-is
SessionCryptoPassphrase secret

#Run /path/to/program to get key
SessionCryptoPassphrase exec:/path/to/program

#Run /path/to/otherProgram and provide arguments
SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"

SessionCryptoPassphraseFile Directive

Description: | File containing keys used to encrypt the session
Syntax: | SessionCryptoPassphraseFile filename
Default: | none
Context: | server config, virtual host, directory
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The SessionCryptoPassphraseFile directive specifies the name of a configuration file containing the keys to use for encrypting or decrypting the session, specified one per line. The file is read on server start, and a graceful restart will be necessary for httpd to pick up changes to the keys.

Unlike the SessionCryptoPassphrase directive, the keys are not exposed within the httpd configuration and can be hidden by protecting the file appropriately.

Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list.


mod_session_dbd - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_session_dbd

Description: | DBD/SQL based session support
Status: | Extension
Module Identifier: | session_dbd_module
Source File: | mod_session_dbd.c
Compatibility: | Available in Apache 2.3 and later

Summary

Warning

The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This submodule of mod_session provides support for the storage of user sessions within a SQL database using the mod_dbd module.

Sessions can either be anonymous, where the session is keyed by a unique UUID string stored on the browser in a cookie, or per user, where the session is keyed against the userid of the logged in user.

SQL based sessions are hidden from the browser, and so offer a measure of privacy without the need for encryption.

Different webservers within a server farm may choose to share a database, and so share sessions with one another.

For more details on the session interface, see the documentation for the mod_session module.

See also

  • mod_session
  • mod_session_crypto
  • mod_session_cookie
  • mod_dbd

DBD Configuration

Before the mod_session_dbd module can be configured to maintain a session, the mod_dbd module must be configured to make the various database queries available to the server.

There are four queries required to keep a session maintained, to select an existing session, to update an existing session, to insert a new session, and to delete an expired or empty session. These queries are configured as per the example below.

Sample DBD configuration

DBDriver pgsql
DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"
DBDPrepareSQL "delete from session where key = %s" deletesession
DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" updatesession
DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession
DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" selectsession
DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession

Anonymous Sessions

Anonymous sessions are keyed against a unique UUID, and stored on the browser within an HTTP cookie. This method is similar to that used by most application servers to store session information.

To create a simple anonymous session and store it in a postgres database table called apachesession, and save the session ID in a cookie called session, configure the session as follows:

SQL based anonymous session

Session On
SessionDBDCookieName session path=/

For more examples on how the session can be configured to be read from and written to by a CGI application, see the mod_session examples section.

For documentation on how the session can be used to store username and password details, see the mod_auth_form module.

Per User Sessions

Per user sessions are keyed against the username of a successfully authenticated user. It offers the most privacy, as no external handle to the session exists outside of the authenticated realm.

Per user sessions work within a correctly configured authenticated environment, be that using basic authentication, digest authentication or SSL client certificates. Due to the limitations of who came first, the chicken or the egg, per user sessions cannot be used to store authentication credentials from a module like mod_auth_form.

To create a simple per user session and store it in a postgres database table called apachesession, and with the session keyed to the userid, configure the session as follows:

SQL based per user session

Session On
SessionDBDPerUser On

Database Housekeeping

Over the course of time, the database can be expected to start accumulating expired sessions. At this point, the mod_session_dbd module is not yet able to handle session expiry automatically.

Warning

The administrator will need to set up an external process via cron to clean out expired sessions.

SessionDBDCookieName Directive

Description: | Name and attributes for the RFC2109 cookie storing the session ID
Syntax: | SessionDBDCookieName name attributes
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDCookieName directive specifies the name and optional attributes of an RFC2109 compliant cookie inside which the session ID will be stored. RFC2109 cookies are set using the Set-Cookie HTTP header.

An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification.

Cookie with attributes

Session On
SessionDBDCookieName session path=/private;domain=example.com;httponly;secure;version=1;

SessionDBDCookieName2 Directive

Description: | Name and attributes for the RFC2965 cookie storing the session ID
Syntax: | SessionDBDCookieName2 name attributes
Default: | none
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDCookieName2 directive specifies the name and optional attributes of an RFC2965 compliant cookie inside which the session ID will be stored. RFC2965 cookies are set using the Set-Cookie2 HTTP header.

An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification.

Cookie2 with attributes

Session On
SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;

SessionDBDCookieRemove Directive

Description: | Control for whether session ID cookies should be removed from incoming HTTP headers
Syntax: | SessionDBDCookieRemove On|Off
Default: | SessionDBDCookieRemove On
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDCookieRemove flag controls whether the cookies containing the session ID will be removed from the headers during request processing.

In a reverse proxy situation where the Apache server acts as a server frontend for a backend origin server, revealing the contents of the session ID cookie to the backend could be a potential privacy violation. When set to on, the session ID cookie will be removed from the incoming HTTP headers.

SessionDBDDeleteLabel Directive

Description: | The SQL query to use to remove sessions from the database
Syntax: | SessionDBDDeleteLabel label
Default: | SessionDBDDeleteLabel deletesession
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDDeleteLabel directive sets the default delete query label to be used to delete an expired or empty session. This label must have been previously defined using the DBDPrepareSQL directive.

SessionDBDInsertLabel Directive

Description: | The SQL query to use to insert sessions into the database
Syntax: | SessionDBDInsertLabel label
Default: | SessionDBDInsertLabel insertsession
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDInsertLabel directive sets the default insert query label to be used to load in a session. This label must have been previously defined using the DBDPrepareSQL directive.

If an attempt to update the session affects no rows, this query will be called to insert the session into the database.

SessionDBDPerUser Directive

Description: | Enable a per user session
Syntax: | SessionDBDPerUser On|Off
Default: | SessionDBDPerUser Off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDPerUser flag enables a per user session keyed against the user's login name. If the user is not logged in, this directive will be ignored.

SessionDBDSelectLabel Directive

Description: | The SQL query to use to select sessions from the database
Syntax: | SessionDBDSelectLabel label
Default: | SessionDBDSelectLabel selectsession
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDSelectLabel directive sets the default select query label to be used to load in a session. This label must have been previously defined using the DBDPrepareSQL directive.

SessionDBDUpdateLabel Directive

Description: | The SQL query to use to update existing sessions in the database
Syntax: | SessionDBDUpdateLabel label
Default: | SessionDBDUpdateLabel updatesession
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_session_dbd

The SessionDBDUpdateLabel directive sets the default update query label to be used to load in a session. This label must have been previously defined using the DBDPrepareSQL directive.

If an attempt to update the session affects no rows, the insert query will be called to insert the session into the database. If the database supports InsertOrUpdate, override this query to perform the update in one query instead of two.


mod_setenvif - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_setenvif

Açıklama: | Ortam değişkenlerinin isteğin özelliklerine uygun olarak atanmasını sağlar
Durum: | Temel
Modül Betimleyici: | setenvif_module
Kaynak Dosyası: | mod_setenvif.c

Özet

mod_setenvif modülü dahili ortam değişkenlerinin isteğin farklı bileşenlerinin belirttiğiniz düzenli ifade ile eşleşmesine bağlı olarak atanmasını mümkün kılar. Bu ortam değişkenleri sunucunun çeşitli kısımlarında yapılacak eylemlerin yanında CGI betiklerinde ve SSI sayfalarında kullanılabilir hale gelmelerine karar verilirken kullanılır.

Yönergeler yapılandırma dosyasında yer aldıkları sıraya göre ele alınırlar. Böylece daha karmaşık dizilimler kullanılabilir, bu örnekteki tarayıcı Mozilla ise netscape ortam değişkeni atanmakta, MSIE ise atanmamaktadır.

BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape

mod_autoindex ile dizin listesi oluşturulması veya bir DirectoryIndex için yol aranması gibi bir dahili alt istek için sunucu yol araması yaparken isteklere özgü ortam değişkenleri alt istekler tarafından miras alınMAZ. Buna ek olarak, mod_setenvif modülünün devreye girdiği API fazlarından dolayı yapılan alt isteklerde SetEnvIf yönergeleri ayrı ayrı değerlendirilMEZ.

Ayrıca bakınız:

  • Apache HTTP Sunucusundaki Ortam Değişkenleri

BrowserMatch Yönergesi

Açıklama: | Ortam değişkenlerini HTTP kullanıcı arayüzüne göre belirler.
Sözdizimi: | BrowserMatch düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_setenvif

BrowserMatch yönergesi SetEnvIf yönergesinin özel bir halidir ve ortam değişkenlerine User-Agent HTTP istek başlığının değerine göre atama yapar. Aşağıdaki iki satır aynı etkiye sahiptir:

BrowserMatch Robot is_a_robot
SetEnvIf User-Agent Robot is_a_robot

Başka örnekler:

BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
BrowserMatch MSIE !javascript

BrowserMatchNoCase Yönergesi

Açıklama: | Ortam değişkenlerini HTTP kullanıcı arayüzünün harf büyüklüğüne duyarsız eşleşmelerine bağlı olarak belirler.
Sözdizimi: | BrowserMatchNoCase düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_setenvif

BrowserMatchNoCase yönergesi sözdizimsel ve anlamsal olarak BrowserMatch yönergesinin eşdeğeridir. Ancak, eşleşmelerde harf büyüklüğüne duyarsızdır. Örnek:

BrowserMatchNoCase mac platform=macintosh
BrowserMatchNoCase win platform=windows

BrowserMatch ve BrowserMatchNoCase yönergeleri SetEnvIf ve SetEnvIfNoCase yönergelerinin özel halleridir. Bu bakımda aşağıdaki iki satır aynı etkiye sahiptir:

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

SetEnvIf Yönergesi

Açıklama: | Ortam değişkenlerini isteğin özniteliklerine göre atar.
Sözdizimi: | SetEnvIf öznitelik düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_setenvif

SetEnvIf yönergesi ortam değişkenlerini isteğin özniteliklerine göre tanımlar. İlk bileşen olarak belirtilen öznitelik şu dört şeyden biri olabilir:

  1. Bir HTTP istek başlığı alanı (ayrıntılı bilgi için bak: RFC2616); örneğin: Host, User-Agent, Referer ve Accept-Language. Bir düzenli ifade kullanılarak birden fazla istek başlığı belirtilebilir.
  2. İsteğin aşağıdaki bileşenlerinden biri:
    • Remote_Host - isteği yapan istemcinin konak ismi (varsa)
    • Remote_Addr -isteği yapan istemcinin IP adresi
    • Server_Addr - isteği alan sunucunun IP adresi (sadece 2.0.43 sonrası sürümler için)
    • Request_Method - kullanılan yöntemin ismi (GET, POST, vs.)
    • Request_Protocol - İsteğin yapıldığı protokolün ismi ve numarası ("HTTP/0.9", "HTTP/1.1" gibi)
    • Request_URI - HTTP istek satırında belirtilen özkaynak; genellikle sorgu dizgesi olmaksızın şema ve konak ismini içeren bir URL parçasıdır. Sorgu dizgeleriyle eşleşmeler hakkında ayrıntılı bilgi edinmek için mod_rewrite modülünün RewriteCond yönergesinin açıklamasına bakınız.
  3. İstek ile evvelce ilişkilendirilmiş bir ortam değişkeninin ismi. Bu sayede önceki bir eşleşmenin sonucuna karşı yeni bir sınama yapma imkanı ortaya çıkar. Böyle bir sınama için sadece evvelce SetEnvIf[NoCase] yönergeleri ile yapılmış atamalardaki ortam değişkenleri kullanılabilir. ‘Evvelce’ derken, sunucu genelinde veya bölüm içinde bu yönergeden önce yer alan SetEnvIf[NoCase] yönerge satırları kastedilmektedir. Ortam değişkenlerinin dikkate alınabilmesi için istek öznitelikleri arasında hiçbir eşleşme olmaması ve öznitelik olarak bir düzenli ifade belirtilmemiş olması gerekir.

İkinci bileşen (düzifd) bir düzenli ifadedir. düzifd ile öznitelik eşleştiği takdirde yönergenin kalan bileşenleri değerlendirmeye alınır.

Kalan bileşenler atanacak ortam değişkenlerinin isimleri ve isteğe bağlı olarak bunlara atanacak değerlerden oluşur. Bunlar şöyle belirtilebilir:

  1. değişken-adı veya
  2. !değişken-adı ya da
  3. değişken-adı=değer

İlk biçemde değişkene "1" değeri atanır. İkincisinde atanmış bir değişken atanmamış yapılır. Üçüncüsünde ise değişkene belirtilen değer bire bir atanır. 2.0.51 sürümünden itibaren Apache httpd parantezli düzenli ifadelerin sonuçları ile değiştirilmek üzere value içinde $1..$9 gösterimleri tanınmaktadır. $0 bu kalıp ile eşleşen tüm dizgeye erişir.

SetEnvIf Request_URI "\.gif$" nesne_bir_resim=gif
SetEnvIf Request_URI "\.jpg$" nesne_bir_resim=jpg
SetEnvIf Request_URI "\.xbm$" nesne_bir_resim=xbm

SetEnvIf Referer belgeler\.alanismi\.example\.com dahili_site_istendi

SetEnvIf object_is_image xbm XBIT_PROCESSING=1

SetEnvIf Request_URI "\.(.*)$" EXTENSION=$1

SetEnvIf ^TS  ^[a-z]  TS_VAR

İlk üçünde istek bir resim dosyası için yapılmışsa nesne_bir_resim ortam değişkeni atanmakta, dördüncüsünde istenen sayfa belgeler.alanismi.example.com adlı sitede bulunuyorsa dahili_site_istendi ortam değişkeni atanmaktadır.

Son örnekte ise istekte "TS" ile başlayıp [a-z] arasındaki karakterlerle devam eden bir başlık alanı varsa TS_VAR ortam değişkeni atanmaktadır.

Ayrıca bakınız:

  • Apache HTTP Sunucusundaki Ortam Değişkenleri belgesinde daha fazla örnek bulunabilir.

SetEnvIfExpr Yönergesi

Açıklama: | Bir ap_expr ifadesine dayanarak ortam değişkenlerine değer atar
Sözdizimi: | SetEnvIfExpr ifade [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_setenvif

SetEnvIfExpr yönergesi bir <If> ap_expr ifadesine dayanarak ortam değişkenlerine değer atar. Bu ifadeler çalışma anında değerlendirilirerek SetEnvIf yönergesindeki gibi ort-değişkenine uygulanır.

SetEnvIfExpr "tolower(req('X-Sendfile')) == 'd:\images\very_big.iso')" iso_delivered

Burada uygulamamızın her X-Sendfile göndermeye çalışmasında ortam değişkenine iso_delivered değeri atanmaktadır.

Uzak IP adresi RFC 1918'e göre özel bir adres ise rfc1918 değişkenine 1 atanması daha kullanışlı bir örnek olurdu:

SetEnvIfExpr "-R '10.0.0.0/8' || -R '172.16.0.0/12' || -R '192.168.0.0/16'" rfc1918

Ayrıca bakınız:

  • Eksiksiz bir kılavuz ve daha fazla örnek için Apache HTTP Sunucusundaki İfadeler belgesine bakınız.
  • Benzer sonuçlara ulaşmak için <If> yönergesi kullanılabilir.
  • mod_filter

SetEnvIfNoCase Yönergesi

Açıklama: | Ortam değişkenlerini isteğin özniteliklerinde harf büyüklüğüne bağlı olmaksızın yapılmış tanımlara göre atar.
Sözdizimi: | SetEnvIfNoCase öznitelik düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ...
Bağlam: | sunucu geneli, sanal konak, dizin, .htaccess
Geçersizleştirme: | FileInfo
Durum: | Temel
Modül: | mod_setenvif

SetEnvIfNoCase yönergesi sözdizimsel ve anlamsal olarak SetEnvIf yönergesinin eşdeğeridir. Ancak, eşleşmelerde harf büyüklüğüne duyarsızdır. Örnek:

SetEnvIfNoCase Host Example\.Org site=example

Burada, Host: HTTP istek başlığında Example.Org, example.org veya harf büyüklüğünce farklı benzerleri belirtilmişse site ortam değişkenine "example" değeri atanmaktadır.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_slotmem_plain - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_slotmem_plain

Description: | Slot-based shared memory provider.
Status: | Extension
Module Identifier: | slotmem_plain_module
Source File: | mod_slotmem_plain.c

Summary

mod_slotmem_plain is a memory provider which provides for creation and access to a plain memory segment in which the datasets are organized in "slots."

If the memory needs to be shared between threads and processes, a better provider would be mod_slotmem_shm.

mod_slotmem_plain provides the following API functions:

apr_status_t doall(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool)
call the callback on all worker slots
apr_status_t create(ap_slotmem_instance_t **new, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool)
create a new slotmem with each item size is item_size.
apr_status_t attach(ap_slotmem_instance_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool)
attach to an existing slotmem.
apr_status_t dptr(ap_slotmem_instance_t *s, unsigned int item_id, void**mem)
get the direct pointer to the memory associated with this worker slot.
apr_status_t get(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len)
get/read the memory from this slot to dest
apr_status_t put(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len)
put/write the data from src to this slot
unsigned int num_slots(ap_slotmem_instance_t *s)
return the total number of slots in the segment
apr_size_t slot_size(ap_slotmem_instance_t *s)
return the total data size, in bytes, of a slot in the segment
apr_status_t grab(ap_slotmem_instance_t *s, unsigned int *item_id);
grab or allocate the first free slot and mark as in-use (does not do any data copying)
apr_status_t fgrab(ap_slotmem_instance_t *s, unsigned int item_id);
forced grab or allocate the specified slot and mark as in-use (does not do any data copying)
apr_status_t release(ap_slotmem_instance_t *s, unsigned int item_id);
release or free a slot and mark as not in-use (does not do any data copying)


mod_slotmem_shm - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_slotmem_shm

Description: | Slot-based shared memory provider.
Status: | Extension
Module Identifier: | slotmem_shm_module
Source File: | mod_slotmem_shm.c

Summary

mod_slotmem_shm is a memory provider which provides for creation and access to a shared memory segment in which the datasets are organized in "slots."

All shared memory is cleared and cleaned with each restart, whether graceful or not. The data itself is stored and restored within a file noted by the name parameter in the create and attach calls. If not specified with an absolute path, the file will be created relative to the path specified by the DefaultRuntimeDir directive.

mod_slotmem_shm provides the following API functions:

apr_status_t doall(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool)
call the callback on all worker slots
apr_status_t create(ap_slotmem_instance_t **new, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool)
create a new slotmem with each item size is item_size. name is used to generate a filename for the persistent store of the shared memory if configured. Values are:
"none"
Anonymous shared memory and no persistent store
"file-name"
[DefaultRuntimeDir]/file-name
"/absolute-file-name"
Absolute file name
apr_status_t attach(ap_slotmem_instance_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool)
attach to an existing slotmem. See create for description of name parameter.
apr_status_t dptr(ap_slotmem_instance_t *s, unsigned int item_id, void**mem)
get the direct pointer to the memory associated with this worker slot.
apr_status_t get(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len)
get/read the memory from this slot to dest
apr_status_t put(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len)
put/write the data from src to this slot
unsigned int num_slots(ap_slotmem_instance_t *s)
return the total number of slots in the segment
apr_size_t slot_size(ap_slotmem_instance_t *s)
return the total data size, in bytes, of a slot in the segment
apr_status_t grab(ap_slotmem_instance_t *s, unsigned int *item_id);
grab or allocate the first free slot and mark as in-use (does not do any data copying)
apr_status_t fgrab(ap_slotmem_instance_t *s, unsigned int item_id);
forced grab or allocate the specified slot and mark as in-use (does not do any data copying)
apr_status_t release(ap_slotmem_instance_t *s, unsigned int item_id);
release or free a slot and mark as not in-use (does not do any data copying)


mod_so - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_so

Açıklama: | Modüllerin ve çalıştırılabilir kodun sunucunun başlatılması veya yeniden başlatılması sırasında yüklenmesini sağlar.
Durum: | Eklenti
Modül Betimleyici: | so_module
Kaynak Dosyası: | mod_so.c
Uyumluluk: | Windows için bu bir temel modüldür (sunucu bunu daima içerir).

Özet

Seçilen işletim sistemleri üzerinde bu modül Apache HTTP Sunucusunun yeniden derlenmesini gerektirmeden modüllerin Devingen Paylaşımlı Nesne (DSO) mekanizması üzerinden kullanılabilmesini sağlar.

Unix’te yüklenen kod genellikle paylaşımlı nesne dosyalarından (.so uzantılı dosyalar), Windows’ta ise ya .so ya da .dll uzantılı dosyalardan gelir.

Uyarı

Apache HTTP Sunucusunun ana sürümlerinden biri (1.3, 2.0, 2.2, 2.4 gibi) için derlenmiş modüller genelde bir diğerinde çalışmaz. Genellikle aralarında API değişikliği sözkonusu olduğundan çalışması için modüllerde yeni sürüme göre değişiklik yapılması gerekir.

Yüklenebilir Modüllerin Windows için Oluşturulması

Bilginize

Windows üzeinde yüklenebilir dosyalar genelde .dll sonekini alırlar. Apache httpd modülleri ise diğer platformlardaki gibi mod_filanca.so biçeminde isimlendirilmektedir. Bununla birlikte, üçüncü parti modüllerden bazılarının (PHP gibi) hala .dll sonekini kullandığı görülmektedir.

mod_so modülü ApacheModuleFoo.dll biçeminde isimlendirilmiş modülleri hala yüklemekteyse de yeni adlandırma uzlaşımı tercih edilmelidir. Yüklenebilir modülleri 2.0’a dönüştürüyorsanız, lütfen isimlerini de 2.0 uzlaşımına uygun hale getiriniz.

Apache httpd modül programlama arayüzü Unix ve Windows sürümleri arasında değişiklik göstermez. Unix için kullanılan çoğu modül hiç değişiklik yapmadan ya da çok küçük bir değişiklikle Windows’ta da çalışmaktadır. Çalışmayanlar Unix platformunun sahip olduğu ancak Windows platformunun sahip olmadığı nitelikleri kullanan modüllerdir.

Bir modül Windows’ta çalıştığı zaman, sunucuya iki şekilde yüklenebilir. Unix’te olduğu gibi, doğrudan sunucunun içinde derlenebilir. Windows için hazırlanan Apache httpd paketi, Unix için geçerli olan Configure betiğini içermediğinden modülün kaynak dosyası ApacheCore proje dosyasına, sembolleri de os\win32\modules.c dosyasına eklenmelidir.

İkinci yol ise modülü bir paylaşımlı kütüphane olarak çalışma anında LoadModule yönergesi ile yüklemek için bir DLL olarak derlemektir. Bu DLL modüller dağıtılabilir ve sunucuyu yeniden derlemek gerekmeksizin her Windows için Apache httpd kurulumunda çalışabilir.

Bir modül DLL’i oluşturmak için modülün kaynak dosyasında küçük bir değişiklik yapmak gerekir: Modül kaydının daha sonra oluşturulacak olan DLL’den ihraç edilebilmesi gerekir (aşağıya bakınız). Bunu yapmak için modülün modül kaydı tanımına (Apache httpd başlık dosyalarında tanımlanmış olan) AP_MODULE_DECLARE_DATA eklenmelidir. Örneğin, modülünüz

module foo_module;

diye bir satır içeriyorsa bunu,

module AP_MODULE_DECLARE_DATA foo_module;

olarak değiştirmelisiniz. Bunun yalnız Windows üzerinde etkili olduğunu ve Unix için modül kodunda bir değişiklik gerekmediğini unutmayınız. Ayrıca, .DEF dosyaları hakkında bilgi sahibi iseniz modül kodunda değişiklik yapmak yerine modül kaydını bu yöntemle de ihraç edebilirsiniz.

Artık modülü içeren bir DLL oluşturmaya hazırsınız. Bunu, libhttpd.dll paylaşımlı kütüphanesi derlenirken oluşturulan libhttpd.lib ihraç kütüphanesi ile ilintilemeniz gerekecektir. Ayrıca, Apache httpd başlık dosyalarının doğru konumlandığından emin olmak için derleyici seçeneklerinde değişiklik yapmanız gerekebilir. Bu kütüphaneyi sunucunuzun kök dizini altındaki modules dizininde bulabilirsiniz. En iyisi derleme ortamının doğru yapılandırıldığından emin olmak için ya ağaçta mevcut modüllerden birinin .dsp dosyasını gaspedersiniz ya da kendi .dsp dosyanızın ilintileme seçenekleriyle derleyicininkileri karşılaştırırsınız.

Artık modülünüzün DLL sürümünü oluşturmalısınız. DLL’i sunucunuzun kök dizininin altında bulunan modules dizinine yerleştirdikten sonra LoadModule yönergesi ile sunucunuza yükleyebilirsiniz.

LoadFile Yönergesi

Açıklama: | Belirtilen nesne dosyasını veya kütüphaneyi sunucu ile ilintiler.
Sözdizimi: | LoadFile dosya-ismi [dosya-ismi] ...
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_so

LoadFile yönergesi ismi belirtilen kütüphaneleri veya nesne dosyalarını sunucu başlatılırken veya yeniden başlatılırken sunucu ile ilintiler. Yönerge, bazı modüllerin çalışması sırasında gereken ek kodların yüklenmesi için kullanılır. dosya-ismi olarak mutlak bir dosya yolu belirtilebileceği gibi ServerRoot’a göreli bir dosya yolu da belirtilebilir.

Örnek:

LoadFile libexec/libxmlparse.so

LoadModule Yönergesi

Açıklama: | Belirtilen nesne dosyasını veya kütüphaneyi sunucu ile ilintiler ve etkin modül listesine ekler.
Sözdizimi: | LoadModule modül dosya-ismi
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_so

LoadModule yönergesi dosya-ismi ile belirtilen nesne dosyasını veya kütüphaneyi sunucu ile ilintiler ve etkin modül listesine belirtilen modül ismiyle ekler. modül, modülün kaynak dosyasında module türündeki tek harici değişkenin ismi olup modül belgelerinde Modül Betimleyici olarak geçer.

Örneğin,

LoadModule status_module modules/mod_status.so

satırı ile ismi belirtilen dosya ServerRoot dizini altındaki modules alt dizininden yüklenir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_socache_dbm - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_socache_dbm

Description: | DBM based shared object cache provider.
Status: | Extension
Module Identifier: | socache_dbm_module
Source File: | mod_socache_dbm.c

Summary

mod_socache_dbm is a shared object cache provider which provides for creation and access to a cache backed by a DBM database.

dbm:/path/to/datafile

Details of other shared object cache providers can be found here.


mod_socache_dc - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_socache_dc

Description: | Distcache based shared object cache provider.
Status: | Extension
Module Identifier: | socache_dc_module
Source File: | mod_socache_dc.c

Summary

mod_socache_dc is a shared object cache provider which provides for creation and access to a cache backed by the distcache distributed session caching libraries.

Details of other shared object cache providers can be found here.


mod_socache_memcache - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_socache_memcache

Description: | Memcache based shared object cache provider.
Status: | Extension
Module Identifier: | socache_memcache_module
Source File: | mod_socache_memcache.c

Summary

mod_socache_memcache is a shared object cache provider which provides for creation and access to a cache backed by the memcached high-performance, distributed memory object caching system.

This shared object cache provider's "create" method requires a comma separated list of memcached host/port specifications. If using this provider via another modules configuration (such as SSLSessionCache), provide the list of servers as the optional "arg" parameter.

SSLSessionCache memcache:memcache.example.com:12345,memcache2.example.com:12345

Details of other shared object cache providers can be found here.

MemcacheConnTTL Directive

Description: | Keepalive time for idle connections
Syntax: | MemcacheConnTTL num[units]
Default: | MemcacheConnTTL 15s
Context: | server config, virtual host
Status: | Extension
Module: | mod_socache_memcache
Compatibility: | Available in Apache 2.4.17 and later

Set the time to keep idle connections with the memcache server(s) alive (threaded platforms only).

Valid values for MemcacheConnTTL are times up to one hour. 0 means no timeout.

This timeout defaults to units of seconds, but accepts suffixes for milliseconds (ms), seconds (s), minutes (min), and hours (h).

Before Apache 2.4.17, this timeout was hardcoded and its value was 600 usec. So, the closest configuration to match the legacy behaviour is to set MemcacheConnTTL to 1ms.

# Set a timeout of 10 minutes
MemcacheConnTTL 10min
# Set a timeout of 60 seconds
MemcacheConnTTL 60

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_socache_shmcb - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_socache_shmcb

Description: | shmcb based shared object cache provider.
Status: | Extension
Module Identifier: | socache_shmcb_module
Source File: | mod_socache_shmcb.c

Summary

mod_socache_shmcb is a shared object cache provider which provides for creation and access to a cache backed by a high-performance cyclic buffer inside a shared memory segment.

shmcb:/path/to/datafile(512000)

Details of other shared object cache providers can be found here.


mod_speling - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_speling

Description: | Attempts to correct mistaken URLs by ignoring capitalization, or attempting to correct various minor misspellings.
Status: | Extension
Module Identifier: | speling_module
Source File: | mod_speling.c

Summary

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 without regard to case, and allowing up to one misspelling (character insertion / omission / transposition or wrong character). A list is built with all document names which were matched using this strategy.

If, after scanning the directory,

  • no matching document was found, Apache will proceed as usual and return a "document not found" error.
  • only one document is found that "almost" matches the request, then it is returned in the form of a redirection response.
  • 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.

CheckCaseOnly Directive

Description: | Limits the action of the speling module to case corrections
Syntax: | CheckCaseOnly on|off
Default: | CheckCaseOnly Off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_speling

When set, this directive limits the action of the spelling correction to lower/upper case changes. Other potential corrections are not performed.

CheckSpelling Directive

Description: | Enables the spelling module
Syntax: | CheckSpelling on|off
Default: | CheckSpelling Off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_speling

This directive enables or disables the spelling module. When enabled, keep in mind that

  • 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.
  • the document trees should not contain sensitive files which could be matched inadvertently by a spelling "correction".
  • the module is unable to correct misspelled user names (as in http://my.host/~apahce/), just file names or directory names.
  • spelling corrections apply strictly to existing files, so a request for the <Location "/status"> may get incorrectly treated as the negotiated file "/stats.html".

mod_speling should not be enabled in DAV enabled directories, because it will try to "spell fix" newly created resource names against existing filenames, e.g., when trying to upload a new document doc43.html it might redirect to an existing document doc34.html, which is not what was intended.


mod_ssl - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ssl

Description: | Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
Status: | Extension
Module Identifier: | ssl_module
Source File: | mod_ssl.c

Summary

This module provides SSL v3 and TLS v1.x support for the Apache HTTP Server. SSL v2 is no longer supported.

This module relies on OpenSSL to provide the cryptography engine.

Further details, discussion, and examples are provided in the SSL documentation.

Environment Variables

This module can be configured to provide several items of SSL information as additional environment variables to the SSI and CGI namespace. This information is not provided by default for performance reasons. (See SSLOptions StdEnvVars, below.) 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 Compatibility chapter for details on the compatibility variables.

Variable Name: | Value Type: | Description:
HTTPS | flag | HTTPS is being used.
SSL_PROTOCOL | string | The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2)
SSL_SESSION_ID | string | The hex-encoded SSL session id
SSL_SESSION_RESUMED | string | Initial or Resumed SSL Session. Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use
SSL_SECURE_RENEG | string | true if secure renegotiation is supported, else false
SSL_CIPHER | string | The cipher specification name
SSL_CIPHER_EXPORT | string | true if cipher is an export cipher
SSL_CIPHER_USEKEYSIZE | number | Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE | number | Number of cipher bits (possible)
SSL_COMPRESS_METHOD | string | SSL compression method negotiated
SSL_VERSION_INTERFACE | string | The mod_ssl program version
SSL_VERSION_LIBRARY | string | The OpenSSL program version
SSL_CLIENT_M_VERSION | string | The version of the client certificate
SSL_CLIENT_M_SERIAL | string | The serial of the client certificate
SSL_CLIENT_S_DN | string | Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 | string | Component of client's Subject DN
SSL_CLIENT_SAN_Email_n | string | Client certificate's subjectAltName extension entries of type rfc822Name
SSL_CLIENT_SAN_DNS_n | string | Client certificate's subjectAltName extension entries of type dNSName
SSL_CLIENT_SAN_OTHER_msUPN_n | string | Client certificate's subjectAltName extension entries of type otherName, Microsoft User Principal Name form (OID 1.3.6.1.4.1.311.20.2.3)
SSL_CLIENT_I_DN | string | Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 | string | Component of client's Issuer DN
SSL_CLIENT_V_START | string | Validity of client's certificate (start time)
SSL_CLIENT_V_END | string | Validity of client's certificate (end time)
SSL_CLIENT_V_REMAIN | string | Number of days until client's certificate expires
SSL_CLIENT_A_SIG | string | Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY | string | Algorithm used for the public key of client's certificate
SSL_CLIENT_CERT | string | PEM-encoded client certificate
SSL_CLIENT_CERT_CHAIN_n | string | PEM-encoded certificates in client certificate chain
SSL_CLIENT_CERT_RFC4523_CEA | string | Serial number and issuer of the certificate. The format matches that of the CertificateExactAssertion in RFC4523
SSL_CLIENT_VERIFY | string | NONE, SUCCESS, GENEROUS or FAILED:reason
SSL_SERVER_M_VERSION | string | The version of the server certificate
SSL_SERVER_M_SERIAL | string | The serial of the server certificate
SSL_SERVER_S_DN | string | Subject DN in server's certificate
SSL_SERVER_SAN_Email_n | string | Server certificate's subjectAltName extension entries of type rfc822Name
SSL_SERVER_SAN_DNS_n | string | Server certificate's subjectAltName extension entries of type dNSName
SSL_SERVER_SAN_OTHER_dnsSRV_n | string | Server certificate's subjectAltName extension entries of type otherName, SRVName form (OID 1.3.6.1.5.5.7.8.7, RFC 4985)
SSL_SERVER_S_DN_x509 | string | Component of server's Subject DN
SSL_SERVER_I_DN | string | Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 | string | Component of server's Issuer DN
SSL_SERVER_V_START | string | Validity of server's certificate (start time)
SSL_SERVER_V_END | string | Validity of server's certificate (end time)
SSL_SERVER_A_SIG | string | Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY | string | Algorithm used for the public key of server's certificate
SSL_SERVER_CERT | string | PEM-encoded server certificate
SSL_SRP_USER | string | SRP username
SSL_SRP_USERINFO | string | SRP user info
SSL_TLS_SNI | string | Contents of the SNI TLS extension (if supplied with ClientHello)

x509 specifies a component of an X.509 DN; one of C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In Apache 2.1 and later, x509 may also include a numeric _n suffix. If the DN in question contains multiple attributes of the same name, this suffix is used as a zero-based index to select a particular attribute. For example, where the server certificate subject DN included two OU attributes, SSL_SERVER_S_DN_OU_0 and SSL_SERVER_S_DN_OU_1 could be used to reference each. A variable name without a _n suffix is equivalent to that name with a _0 suffix; the first (or only) attribute. When the environment table is populated using the StdEnvVars option of the SSLOptions directive, the first (or only) attribute of any DN is added only under a non-suffixed name; i.e. no _0 suffixed entries are added.

The format of the *_DN variables has changed in Apache HTTPD 2.3.11. See the LegacyDNStringFormat option for SSLOptions for details.

SSL_CLIENT_V_REMAIN is only available in version 2.1 and later.

A number of additional environment variables can also be used in SSLRequire expressions, or in custom log formats:

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
THE_REQUEST            SERVER_NAME           TIME_MIN
REQUEST_FILENAME       SERVER_PORT           TIME_SEC
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
REQUEST_SCHEME         REMOTE_ADDR           TIME
REQUEST_URI            REMOTE_USER

In these contexts, two special formats can also be used:

ENV:variablename
This will expand to the standard environment variable variablename.
HTTP:headername
This will expand to the value of the request header with name headername.

Custom Log Formats

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config. First there is an additional ``%{varname}x'' 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.

For backward compatibility there is additionally a special ``%{name}c'' cryptography format function provided. Information about this function is provided in the Compatibility chapter.

Example

CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

These formats even work without setting the StdEnvVars option of the SSLOptions directive.

Request Notes

mod_ssl sets "notes" for the request which can be used in logging with the %{name}n format string in mod_log_config.

The notes supported are as follows:

ssl-access-forbidden
This note is set to the value 1 if access was denied due to an SSLRequire or SSLRequireSSL directive.
ssl-secure-reneg
If mod_ssl is built against a version of OpenSSL which supports the secure renegotiation extension, this note is set to the value 1 if SSL is in used for the current connection, and the client also supports the secure renegotiation extension. If the client does not support the secure renegotiation extension, the note is set to the value 0. If mod_ssl is not built against a version of OpenSSL which supports secure renegotiation, or if SSL is not in use for the current connection, the note is not set.

Expression Parser Extension

When mod_ssl is built into Apache or at least loaded (under DSO situation) any variables provided by mod_ssl can be used in expressions for the ap_expr Expression Parser. The variables can be referenced using the syntax ``%{varname}''. Starting with version 2.4.18 one can also use the mod_rewrite style syntax ``%{SSL:varname}'' or the function style syntax ``ssl(varname)''.

Example (using mod_headers)

Header set X-SSL-PROTOCOL "expr=%{SSL_PROTOCOL}"
Header set X-SSL-CIPHER "expr=%{SSL:SSL_CIPHER}"

This feature even works without setting the StdEnvVars option of the SSLOptions directive.

Authorization providers for use with Require

mod_ssl provides a few authentication providers for use with mod_authz_core's Require directive.

Require ssl

The ssl provider denies access if a connection is not encrypted with SSL. This is similar to the SSLRequireSSL directive.

Require ssl

Require ssl-verify-client

The ssl provider allows access if the user is authenticated with a valid client certificate. This is only useful if SSLVerifyClient optional is in effect.

The following example grants access if the user is authenticated either with a client certificate or by username and password.

      Require ssl-verify-client

      Require valid-user

SSLCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients 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 SSLCACertificatePath.

Example

SSLCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt"

SSLCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

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.

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 hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.

Example

SSLCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

SSLCADNRequestFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for defining acceptable CA names
Syntax: | SSLCADNRequestFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

When a client certificate is requested by mod_ssl, a list of acceptable Certificate Authority names is sent to the client in the SSL handshake. These CA names can be used by the client to select an appropriate client certificate out of those it has available.

If neither of the directives SSLCADNRequestPath or SSLCADNRequestFile are given, then the set of acceptable CA names sent to the client is the names of all the CA certificates given by the SSLCACertificateFile and SSLCACertificatePath directives; in other words, the names of the CAs which will actually be used to verify the client certificate.

In some circumstances, it is useful to be able to send a set of acceptable CA names which differs from the actual CAs used to verify the client certificate - for example, if the client certificates are signed by intermediate CAs. In such cases, SSLCADNRequestPath and/or SSLCADNRequestFile can be used; the acceptable CA names are then taken from the complete set of certificates in the directory and/or file specified by this pair of directives.

SSLCADNRequestFile must specify an all-in-one file containing a concatenation of PEM-encoded CA certificates.

Example

SSLCADNRequestFile "/usr/local/apache2/conf/ca-names.crt"

SSLCADNRequestPath Directive

Description: | Directory of PEM-encoded CA Certificates for defining acceptable CA names
Syntax: | SSLCADNRequestPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This optional directive can be used to specify the set of acceptable CA names which will be sent to the client when a client certificate is requested. See the SSLCADNRequestFile directive for more details.

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 hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.

Example

SSLCADNRequestPath "/usr/local/apache2/conf/ca-names.crt/"

SSLCARevocationCheck Directive

Description: | Enable CRL-based revocation checking
Syntax: | SSLCARevocationCheck chain|leaf|none
Default: | SSLCARevocationCheck none
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

Enables certificate revocation list (CRL) checking. At least one of SSLCARevocationFile or SSLCARevocationPath must be configured. When set to chain (recommended setting), CRL checks are applied to all certificates in the chain, while setting it to leaf limits the checks to the end-entity cert.

When set to chain or leaf, CRLs must be available for successful validation

Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when no CRL(s) were found in any of the locations configured with SSLCARevocationFile or SSLCARevocationPath. With the introduction of this directive, the behavior has been changed: when checking is enabled, CRLs must be present for the validation to succeed - otherwise it will fail with an "unable to get certificate CRL" error.

Example

SSLCARevocationCheck chain

SSLCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients 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 SSLCARevocationPath.

Example

SSLCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl"

SSLCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

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.

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 hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links.

Example

SSLCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

SSLCertificateChainFile Directive

Description: | File of PEM-encoded Server CA Certificates
Syntax: | SSLCertificateChainFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

SSLCertificateChainFile is deprecated

SSLCertificateChainFile became obsolete with version 2.4.8, when SSLCertificateFile was extended to also load intermediate CA certificates from the server certificate file.

This directive sets the optional all-in-one 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 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.

This should be used alternatively and/or additionally to SSLCACertificatePath 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 SSLCACertificatePath 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.

But be careful: Providing the certificate chain works only if you are using a single RSA or DSA based server certificate. If you are using a coupled RSA+DSA certificate pair, this will work only if actually both certificates use the same certificate chain. Else the browsers will be confused in this situation.

Example

SSLCertificateChainFile "/usr/local/apache2/conf/ssl.crt/ca.crt"

SSLCertificateFile Directive

Description: | Server PEM-encoded X.509 certificate data file
Syntax: | SSLCertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to a file with certificate data in PEM format. At a minimum, the file must include an end-entity (leaf) certificate. The directive can be used multiple times (referencing different filenames) to support multiple algorithms for server authentication - typically RSA, DSA, and ECC. The number of supported algorithms depends on the OpenSSL version being used for mod_ssl: with version 1.0.0 or later, openssl list-public-key-algorithms will output a list of supported algorithms, see also the note below about limitations of OpenSSL versions prior to 1.0.2 and the ways to work around them.

The files may also include intermediate CA certificates, sorted from leaf to root. This is supported with version 2.4.8 and later, and obsoletes SSLCertificateChainFile. When running with OpenSSL 1.0.2 or later, this allows to configure the intermediate CA chain on a per-certificate basis.

Custom DH parameters and an EC curve name for ephemeral keys, can also be added to end of the first file configured using SSLCertificateFile. This is supported in version 2.4.7 or later. Such parameters can be generated using the commands openssl dhparam and openssl ecparam. The parameters can be added as-is to the end of the first certificate file. Only the first file can be used for custom parameters, as they are applied independently of the authentication algorithm type.

Finally the end-entity certificate's private key can also be added to the certificate file instead of using a separate SSLCertificateKeyFile directive. This practice is highly discouraged. If it is used, the certificate files using such an embedded key must be configured after the certificates using a separate key file. If the private key is encrypted, the pass phrase dialog is forced at startup time.

DH parameter interoperability with primes > 1024 bit

Beginning with version 2.4.7, mod_ssl makes use of standardized DH parameters with prime lengths of 2048, 3072 and 4096 bits and with additional prime lengths of 6144 and 8192 bits beginning with version 2.4.10 (from RFC 3526), and hands them out to clients based on the length of the certificate's RSA/DSA key. With Java-based clients in particular (Java 7 or earlier), this may lead to handshake failures - see this FAQ answer for working around such issues.

Default DH parameters when using multiple certificates and OpenSSL versions prior to 1.0.2

When using multiple certificates to support different authentication algorithms (like RSA, DSA, but mainly ECC) and OpenSSL prior to 1.0.2, it is recommended to either use custom DH parameters (preferably) by adding them to the first certificate file (as described above), or to order the SSLCertificateFile directives such that RSA/DSA certificates are placed after the ECC one.

This is due to a limitation in older versions of OpenSSL which don't let the Apache HTTP Server determine the currently selected certificate at handshake time (when the DH parameters must be sent to the peer) but instead always provide the last configured certificate. Consequently, the server may select default DH parameters based on the length of the wrong certificate's key (ECC keys are much smaller than RSA/DSA ones and their length is not relevant for selecting DH primes).

Since custom DH parameters always take precedence over the default ones, this issue can be avoided by creating and configuring them (as described above), thus using a custom/suitable length.

Example

SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"

SSLCertificateKeyFile Directive

Description: | Server PEM-encoded private key file
Syntax: | SSLCertificateKeyFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to the PEM-encoded private key file for the server. If the contained private key is encrypted, the pass phrase dialog is forced at startup time.

The directive can be used multiple times (referencing different filenames) to support multiple algorithms for server authentication. For each SSLCertificateKeyFile directive, there must be a matching SSLCertificateFile directive.

The private key may also be combined with the certificate in the file given by SSLCertificateFile, but this practice is highly discouraged. If it is used, the certificate files using such an embedded key must be configured after the certificates using a separate key file.

Example

SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"

SSLCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL handshake
Syntax: | SSLCipherSuite cipher-spec
Default: | SSLCipherSuite DEFAULT (depends on OpenSSL version)
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This complex directive uses a colon-separated cipher-spec 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 renegotiation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent.

An SSL cipher specification in cipher-spec is composed of 4 major attributes plus a few extra minor ones:

  • Key Exchange Algorithm:
    RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password
  • Authentication Algorithm:
    RSA, Diffie-Hellman, DSS, ECDSA, or none.
  • Cipher/Encryption Algorithm:
    AES, DES, Triple-DES, RC4, RC2, IDEA, etc.
  • MAC Digest Algorithm:
    MD5, SHA or SHA1, SHA256, SHA384.

An SSL cipher can also be an export cipher. SSLv2 ciphers are no longer supported. 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 Table 1). The actually available ciphers and aliases depends on the used openssl version. Newer openssl versions may include additional ciphers.

Tag | Description
Key Exchange Algorithm:
kRSA | RSA key exchange
kDHr | Diffie-Hellman key exchange with RSA key
kDHd | Diffie-Hellman key exchange with DSA key
kEDH | Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
kSRP | Secure Remote Password (SRP) key exchange
Authentication Algorithm:
aNULL | No authentication
aRSA | RSA authentication
aDSS | DSS authentication
aDH | Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL | No encryption
NULL | alias for eNULL
AES | AES encryption
DES | DES encryption
3DES | Triple-DES encryption
RC4 | RC4 encryption
RC2 | RC2 encryption
IDEA | IDEA encryption
MAC Digest Algorithm:
MD5 | MD5 hash function
SHA1 | SHA1 hash function
SHA | alias for SHA1
SHA256 | SHA256 hash function
SHA384 | SHA384 hash function
Aliases:
SSLv3 | all SSL version 3.0 ciphers
TLSv1 | all TLS version 1.0 ciphers
EXP | all export ciphers
EXPORT40 | all 40-bit export ciphers only
EXPORT56 | all 56-bit export ciphers only
LOW | all low strength ciphers (no export, single DES)
MEDIUM | all ciphers with 128 bit encryption
HIGH | all ciphers using Triple-DES
RSA | all ciphers using RSA key exchange
DH | all ciphers using Diffie-Hellman key exchange
EDH | all ciphers using Ephemeral Diffie-Hellman key exchange
ECDH | Elliptic Curve Diffie-Hellman key exchange
ADH | all ciphers using Anonymous Diffie-Hellman key exchange
AECDH | all ciphers using Anonymous Elliptic Curve Diffie-Hellman key exchange
SRP | all ciphers using Secure Remote Password (SRP) key exchange
DSS | all ciphers using DSS authentication
ECDSA | all ciphers using ECDSA authentication
aNULL | all ciphers using no authentication

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 (SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) for certain groups of ciphers. These tags can be joined together with prefixes to form the cipher-spec. Available prefixes are:

  • none: add cipher to list
  • +: move matching ciphers to the current location in list
  • -: remove cipher from list (can be added later again)
  • !: kill cipher from list completely (can not be added later again)

aNULL, eNULL and EXP ciphers are always disabled

Beginning with version 2.4.7, null and export-grade ciphers are always disabled, as mod_ssl unconditionally adds !aNULL:!eNULL:!EXP to any cipher string at initialization.

A simpler way to look at all of this is to use the ``openssl ciphers -v'' command which provides a nice way to successively create the correct cipher-spec string. The default cipher-spec string depends on the version of the OpenSSL libraries used. Let's suppose it is ``RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5'' which means the following: Put RC4-SHA and AES128-SHA at the beginning. We do this, because these ciphers offer a good compromise between speed and security. Next, include high and medium security ciphers. Finally, remove all ciphers which do not authenticate, i.e. for SSL the Anonymous Diffie-Hellman ciphers, as well as all ciphers which use MD5 as hash algorithm, because it has been proven insufficient.

$ openssl ciphers -v 'RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5'
RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
AES128-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(128)  Mac=SHA1
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
...                     ...               ...     ...           ...
SEED-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=SEED(128) Mac=SHA1
PSK-RC4-SHA             SSLv3 Kx=PSK      Au=PSK  Enc=RC4(128)  Mac=SHA1
KRB5-RC4-SHA            SSLv3 Kx=KRB5     Au=KRB5 Enc=RC4(128)  Mac=SHA1

The complete list of particular RSA & DH ciphers for SSL is given in Table 2.

Example

SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
Cipher-Tag | Protocol | Key Ex. | Auth. | Enc. | MAC | Type
RSA Ciphers:
DES-CBC3-SHA | SSLv3 | RSA | RSA | 3DES(168) | SHA1 |
IDEA-CBC-SHA | SSLv3 | RSA | RSA | IDEA(128) | SHA1 |
RC4-SHA | SSLv3 | RSA | RSA | RC4(128) | SHA1 |
RC4-MD5 | SSLv3 | RSA | RSA | RC4(128) | MD5 |
DES-CBC-SHA | SSLv3 | RSA | RSA | DES(56) | SHA1 |
EXP-DES-CBC-SHA | SSLv3 | RSA(512) | RSA | DES(40) | SHA1 | export
EXP-RC2-CBC-MD5 | SSLv3 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv3 | RSA(512) | RSA | RC4(40) | MD5 | export
NULL-SHA | SSLv3 | RSA | RSA | None | SHA1 |
NULL-MD5 | SSLv3 | RSA | RSA | None | MD5 |
Diffie-Hellman Ciphers:
ADH-DES-CBC3-SHA | SSLv3 | DH | None | 3DES(168) | SHA1 |
ADH-DES-CBC-SHA | SSLv3 | DH | None | DES(56) | SHA1 |
ADH-RC4-MD5 | SSLv3 | DH | None | RC4(128) | MD5 |
EDH-RSA-DES-CBC3-SHA | SSLv3 | DH | RSA | 3DES(168) | SHA1 |
EDH-DSS-DES-CBC3-SHA | SSLv3 | DH | DSS | 3DES(168) | SHA1 |
EDH-RSA-DES-CBC-SHA | SSLv3 | DH | RSA | DES(56) | SHA1 |
EDH-DSS-DES-CBC-SHA | SSLv3 | DH | DSS | DES(56) | SHA1 |
EXP-EDH-RSA-DES-CBC-SHA | SSLv3 | DH(512) | RSA | DES(40) | SHA1 | export
EXP-EDH-DSS-DES-CBC-SHA | SSLv3 | DH(512) | DSS | DES(40) | SHA1 | export
EXP-ADH-DES-CBC-SHA | SSLv3 | DH(512) | None | DES(40) | SHA1 | export
EXP-ADH-RC4-MD5 | SSLv3 | DH(512) | None | RC4(40) | MD5 | export

SSLCompression Directive

Description: | Enable compression on the SSL level
Syntax: | SSLCompression on|off
Default: | SSLCompression off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.3 and later, if using OpenSSL 0.9.8 or later; virtual host scope available if using OpenSSL 1.0.0 or later. The default used to be on in version 2.4.3.

This directive allows to enable compression on the SSL level.

Enabling compression causes security issues in most setups (the so called CRIME attack).

SSLCryptoDevice Directive

Description: | Enable use of a cryptographic hardware accelerator
Syntax: | SSLCryptoDevice engine
Default: | SSLCryptoDevice builtin
Context: | server config
Status: | Extension
Module: | mod_ssl

This directive enables use of a cryptographic hardware accelerator board to offload some of the SSL processing overhead. This directive can only be used if the SSL toolkit is built with "engine" support; OpenSSL 0.9.7 and later releases have "engine" support by default, the separate "-engine" releases of OpenSSL 0.9.6 must be used.

To discover which engine names are supported, run the command "openssl engine".

Example

# For a Broadcom accelerator:
SSLCryptoDevice ubsec

SSLEngine Directive

Description: | SSL Engine Operation Switch
Syntax: | SSLEngine on|off|optional
Default: | SSLEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine. This is should be used inside a <VirtualHost> section to enable SSL/TLS for a that virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLEngine on
#...
</VirtualHost>

In Apache 2.1 and later, SSLEngine can be set to optional. This enables support for RFC 2817, Upgrading to TLS Within HTTP/1.1. At this time no web browsers support RFC 2817.

SSLFIPS Directive

Description: | SSL FIPS mode Switch
Syntax: | SSLFIPS on|off
Default: | SSLFIPS off
Context: | server config
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL library FIPS_mode flag. It must be set in the global server context and cannot be configured with conflicting settings (SSLFIPS on followed by SSLFIPS off or similar). The mode applies to all SSL library operations.

If httpd was compiled against an SSL library which did not support the FIPS_mode flag, SSLFIPS on will fail. Refer to the FIPS 140-2 Security Policy document of the SSL provider library for specific requirements to use mod_ssl in a FIPS 140-2 approved mode of operation; note that mod_ssl itself is not validated, but may be described as using FIPS 140-2 validated cryptographic module, when all components are assembled and operated under the guidelines imposed by the applicable Security Policy.

SSLHonorCipherOrder Directive

Description: | Option to prefer the server's cipher preference order
Syntax: | SSLHonorCipherOrder on|off
Default: | SSLHonorCipherOrder off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the client's preference is used. If this directive is enabled, the server's preference will be used instead.

Example

SSLHonorCipherOrder on

SSLInsecureRenegotiation Directive

Description: | Option to enable support for insecure renegotiation
Syntax: | SSLInsecureRenegotiation on|off
Default: | SSLInsecureRenegotiation off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.2.15 and later, if using OpenSSL 0.9.8m or later

As originally specified, all versions of the SSL and TLS protocols (up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle attack (CVE-2009-3555) during a renegotiation. This vulnerability allowed an attacker to "prefix" a chosen plaintext to the HTTP request as seen by the web server. A protocol extension was developed which fixed this vulnerability if supported by both client and server.

If mod_ssl is linked against OpenSSL version 0.9.8m or later, by default renegotiation is only supported with clients supporting the new protocol extension. If this directive is enabled, renegotiation will be allowed with old (unpatched) clients, albeit insecurely.

Security warning

If this directive is enabled, SSL connections will be vulnerable to the Man-in-the-Middle prefix attack as described in CVE-2009-3555.

Example

SSLInsecureRenegotiation on

The SSL_SECURE_RENEG environment variable can be used from an SSI or CGI script to determine whether secure renegotiation is supported for a given SSL connection.

SSLOCSPDefaultResponder Directive

Description: | Set the default responder URI for OCSP validation
Syntax: | SSLOCSDefaultResponder uri
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option sets the default OCSP responder to use. If SSLOCSPOverrideResponder is not enabled, the URI given will be used only if no responder URI is specified in the certificate being verified.

SSLOCSPEnable Directive

Description: | Enable OCSP validation of the client certificate chain
Syntax: | SSLOCSPEnable on|off
Default: | SSLOCSPEnable off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option enables OCSP validation of the client certificate chain. If this option is enabled, certificates in the client's certificate chain will be validated against an OCSP responder after normal verification (including CRL checks) have taken place.

The OCSP responder used is either extracted from the certificate itself, or derived by configuration; see the SSLOCSPDefaultResponder and SSLOCSPOverrideResponder directives.

Example

SSLVerifyClient on
SSLOCSPEnable on
SSLOCSPDefaultResponder "http://responder.example.com:8888/responder"
SSLOCSPOverrideResponder on

SSLOCSPOverrideResponder Directive

Description: | Force use of the default responder URI for OCSP validation
Syntax: | SSLOCSPOverrideResponder on|off
Default: | SSLOCSPOverrideResponder off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option forces the configured default OCSP responder to be used during OCSP certificate validation, regardless of whether the certificate being validated references an OCSP responder.

SSLOCSPProxyURL Directive

Description: | Proxy URL to use for OCSP requests
Syntax: | SSLOCSPProxyURL url
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.19 and later

This option allows to set the URL of a HTTP proxy that should be used for all queries to OCSP responders.

SSLOCSPResponderTimeout Directive

Description: | Timeout for OCSP queries
Syntax: | SSLOCSPResponderTimeout seconds
Default: | SSLOCSPResponderTimeout 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option sets the timeout for queries to OCSP responders, when SSLOCSPEnable is turned on.

SSLOCSPResponseMaxAge Directive

Description: | Maximum allowable age for OCSP responses
Syntax: | SSLOCSPResponseMaxAge seconds
Default: | SSLOCSPResponseMaxAge -1
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option sets the maximum allowable age ("freshness") for OCSP responses. The default value (-1) does not enforce a maximum age, which means that OCSP responses are considered valid as long as their nextUpdate field is in the future.

SSLOCSPResponseTimeSkew Directive

Description: | Maximum allowable time skew for OCSP response validation
Syntax: | SSLOCSPResponseTimeSkew seconds
Default: | SSLOCSPResponseTimeSkew 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This option sets the maximum allowable time skew for OCSP responses (when checking their thisUpdate and nextUpdate fields).

SSLOCSPUseRequestNonce Directive

Description: | Use a nonce within OCSP queries
Syntax: | SSLOCSPUseRequestNonce on|off
Default: | SSLOCSPUseRequestNonce on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.10 and later

This option determines whether queries to OCSP responders should contain a nonce or not. By default, a query nonce is always used and checked against the response's one. When the responder does not use nonces (e.g. Microsoft OCSP Responder), this option should be turned off.

SSLOpenSSLConfCmd Directive

Description: | Configure OpenSSL parameters through its SSL_CONF API
Syntax: | SSLOpenSSLConfCmd command-name command-value
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.8 and later, if using OpenSSL 1.0.2 or later

This directive exposes OpenSSL's SSL_CONF API to mod_ssl, allowing a flexible configuration of OpenSSL parameters without the need of implementing additional mod_ssl directives when new features are added to OpenSSL.

The set of available SSLOpenSSLConfCmd commands depends on the OpenSSL version being used for mod_ssl (at least version 1.0.2 is required). For a list of supported command names, see the section Supported configuration file commands in the SSL_CONF_cmd(3) manual page for OpenSSL.

Some of the SSLOpenSSLConfCmd commands can be used as an alternative to existing directives (such as SSLCipherSuite or SSLProtocol), though it should be noted that the syntax / allowable values for the parameters may sometimes differ.

Examples

SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference
SSLOpenSSLConfCmd ECDHParameters brainpoolP256r1
SSLOpenSSLConfCmd ServerInfoFile "/usr/local/apache2/conf/server-info.pem"
SSLOpenSSLConfCmd Protocol "-ALL, TLSv1.2"
SSLOpenSSLConfCmd SignatureAlgorithms RSA+SHA384:ECDSA+SHA256

SSLOptions Directive

Description: | Configure various SSL engine run-time options
Syntax: | SSLOptions [+|-]option ...
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control various run-time options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) 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.

The available options are:

  • StdEnvVars

    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.

  • ExportCertData

    When this option is enabled, additional CGI/SSI environment variables are created: SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN_n (with n = 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.

  • FakeBasicAuth

    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 openssl x509 command: openssl x509 -noout -subject -in certificate.crt). Note that no password is obtained from the user. Every entry in the user file needs this password: ``xxj31ZMTZzkVA'', which is the DES-encrypted version of the word `password''. 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: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

    Note that the AuthBasicFake directive within mod_auth_basic can be used as a more general mechanism for faking basic authentication, giving control over the structure of both the username and password.

  • StrictRequire

    This forces forbidden access when SSLRequireSSL or SSLRequire successfully decided that access should be forbidden. Usually the default is that in the case where a ``Satisfy any'' directive is used, and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that's how the Apache Satisfy mechanism should work.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an ``SSLOptions +StrictRequire''. Then an additional ``Satisfy Any'' has no chance once mod_ssl has decided to deny access.

  • OptRenegotiate

    This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full 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 may not be what the user expects, so enable this on a per-directory basis only, please.

  • LegacyDNStringFormat

    This option influences how values of the SSL_{CLIENT,SERVER}_{I,S}_DN variables are formatted. Since version 2.3.11, Apache HTTPD uses a RFC 2253 compatible format by default. This uses commas as delimiters between the attributes, allows the use of non-ASCII characters (which are converted to UTF8), escapes various special characters with backslashes, and sorts the attributes with the "C" attribute last.

    If LegacyDNStringFormat is set, the old format will be used which sorts the "C" attribute first, uses slashes as separators, and does not handle non-ASCII and special characters in any consistent way.

Example

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
    SSLOptions +StdEnvVars -ExportCertData
</Files>

SSLPassPhraseDialog Directive

Description: | Type of pass phrase dialog for encrypted private keys
Syntax: | SSLPassPhraseDialog type
Default: | SSLPassPhraseDialog builtin
Context: | server config
Status: | Extension
Module: | mod_ssl

When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) 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 type:

  • builtin

    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).

    This scheme allows mod_ssl to be maximally flexible (because for N encrypted Private Key files you can 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).

  • |/path/to/program [args...]

    This mode allows an external program to be used which acts as a pipe to a particular input device; the program is sent the standard prompt text used for the builtin mode on stdin, and is expected to write password strings on stdout. If several passwords are needed (or an incorrect password is entered), additional prompt text will be written subsequent to the first password being returned, and more passwords must then be written back.

  • exec:/path/to/program

    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 ``servername:portnumber'', the second is either ``RSA'', ``DSA'', ``ECC'' or an integer index starting at 3 if more than three keys are configured), which indicate for which server and algorithm it has to print the corresponding Pass Phrase to stdout. In versions 2.4.8 (unreleased) and 2.4.9, it is called with one argument, a string of the form ``servername:portnumber:index'' (with index being a zero-based integer number), which indicate the server, TCP port and certificate number. 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.

    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 stdout. 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.

    The reuse-algorithm above is used here, too. In other words: The external program is called only once per unique Pass Phrase.

Example

SSLPassPhraseDialog "exec:/usr/local/apache/sbin/pp-filter"

SSLProtocol Directive

Description: | Configure usable SSL/TLS protocol versions
Syntax: | SSLProtocol [+|-]protocol ...
Default: | SSLProtocol all -SSLv3 (up to 2.4.16: all)
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive can be used to control which versions of the SSL/TLS protocol will be accepted in new connections.

The available (case-insensitive) protocols are:

  • SSLv3

    This is the Secure Sockets Layer (SSL) protocol, version 3.0, from the Netscape Corporation. It is the successor to SSLv2 and the predecessor to TLSv1, but is deprecated in RFC 7568.

  • TLSv1

    This is the Transport Layer Security (TLS) protocol, version 1.0. It is the successor to SSLv3 and is defined in RFC 2246. It is supported by nearly every client.

  • TLSv1.1 (when using OpenSSL 1.0.1 and later)

    A revision of the TLS 1.0 protocol, as defined in RFC 4346.

  • TLSv1.2 (when using OpenSSL 1.0.1 and later)

    A revision of the TLS 1.1 protocol, as defined in RFC 5246.

  • all

    This is a shortcut for ``+SSLv3 +TLSv1'' or - when using OpenSSL 1.0.1 and later - ``+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2'', respectively (except for OpenSSL versions compiled with the ``no-ssl3'' configuration option, where all does not include +SSLv3).

Example

SSLProtocol TLSv1

SSLProxyCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server 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 SSLProxyCACertificatePath.

Example

SSLProxyCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt"

SSLProxyCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose remote servers you deal with. These are used to verify the remote server certificate on Remote Server Authentication.

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 hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.

Example

SSLProxyCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

SSLProxyCARevocationCheck Directive

Description: | Enable CRL-based revocation checking for Remote Server Auth
Syntax: | SSLProxyCARevocationCheck chain|leaf|none
Default: | SSLProxyCARevocationCheck none
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

Enables certificate revocation list (CRL) checking for the remote servers you deal with. At least one of SSLProxyCARevocationFile or SSLProxyCARevocationPath must be configured. When set to chain (recommended setting), CRL checks are applied to all certificates in the chain, while setting it to leaf limits the checks to the end-entity cert.

When set to chain or leaf, CRLs must be available for successful validation

Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when no CRL(s) were found in any of the locations configured with SSLProxyCARevocationFile or SSLProxyCARevocationPath. With the introduction of this directive, the behavior has been changed: when checking is enabled, CRLs must be present for the validation to succeed - otherwise it will fail with an "unable to get certificate CRL" error.

Example

SSLProxyCARevocationCheck chain

SSLProxyCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server 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 SSLProxyCARevocationPath.

Example

SSLProxyCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl"

SSLProxyCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. These are used to revoke the remote server certificate on Remote Server Authentication.

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 hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links.

Example

SSLProxyCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

SSLProxyCheckPeerCN Directive

Description: | Whether to check the remote server certificate's CN field
Syntax: | SSLProxyCheckPeerCN on|off
Default: | SSLProxyCheckPeerCN on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets whether the remote server certificate's CN field is compared against the hostname of the request URL. If both are not equal a 502 status code (Bad Gateway) is sent.

In 2.4.5 and later, SSLProxyCheckPeerCN has been superseded by SSLProxyCheckPeerName, and its setting is only taken into account when SSLProxyCheckPeerName off is specified at the same time.

Example

SSLProxyCheckPeerCN on

SSLProxyCheckPeerExpire Directive

Description: | Whether to check if remote server certificate is expired
Syntax: | SSLProxyCheckPeerExpire on|off
Default: | SSLProxyCheckPeerExpire on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets whether it is checked if the remote server certificate is expired or not. If the check fails a 502 status code (Bad Gateway) is sent.

Example

SSLProxyCheckPeerExpire on

SSLProxyCheckPeerName Directive

Description: | Configure host name checking for remote server certificates
Syntax: | SSLProxyCheckPeerName on|off
Default: | SSLProxyCheckPeerName on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Apache HTTP Server 2.4.5 and later

This directive configures host name checking for server certificates when mod_ssl is acting as an SSL client. The check will succeed if the host name from the request URI is found in either the subjectAltName extension or (one of) the CN attribute(s) in the certificate's subject. If the check fails, the SSL request is aborted and a 502 status code (Bad Gateway) is returned. The directive supersedes SSLProxyCheckPeerCN, which only checks for the expected host name in the first CN attribute.

Wildcard matching is supported in one specific flavor: subjectAltName entries of type dNSName or CN attributes starting with *. will match for any DNS name with the same number of labels and the same suffix (i.e., *.example.org matches for foo.example.org, but not for foo.bar.example.org).

SSLProxyCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL proxy handshake
Syntax: | SSLProxyCipherSuite cipher-spec
Default: | SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

Equivalent to SSLCipherSuite, but for the proxy connection. Please refer to SSLCipherSuite for additional information.

SSLProxyEngine Directive

Description: | SSL Proxy Engine Operation Switch
Syntax: | SSLProxyEngine on|off
Default: | SSLProxyEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This is usually used inside a <VirtualHost> section to enable SSL/TLS for proxy usage in a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for proxy both for the main server and all configured virtual hosts.

Note that the SSLProxyEngine directive should not, in general, be included in a virtual host that will be acting as a forward proxy (using <Proxy> or <ProxyRequest> directives. SSLProxyEngine is not required to enable a forward proxy server to proxy SSL/TLS requests.

Example

<VirtualHost _default_:443>
    SSLProxyEngine on
    #...
</VirtualHost>

SSLProxyMachineCertificateChainFile Directive

Description: | File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate
Syntax: | SSLProxyMachineCertificateChainFile filename
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you keep the certificate chain for all of the client certs in use. This directive will be needed if the remote server presents a list of CA certificates that are not direct signers of one of the configured client certificates.

This referenced file is simply the concatenation of the various PEM-encoded certificate files. Upon startup, each client certificate configured will be examined and a chain of trust will be constructed.

Security warning

If this directive is enabled, all of the certificates in the file will be trusted as if they were also in SSLProxyCACertificateFile.

Example

SSLProxyMachineCertificateChainFile "/usr/local/apache2/conf/ssl.crt/proxyCA.pem"

SSLProxyMachineCertificateFile Directive

Description: | File of concatenated PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificateFile filename
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you keep the certificates and keys used for authentication of the proxy server to remote servers.

This referenced file is simply the concatenation of the various PEM-encoded certificate files, in order of preference. Use this directive alternatively or additionally to SSLProxyMachineCertificatePath.

Currently there is no support for encrypted private keys

Example

SSLProxyMachineCertificateFile "/usr/local/apache2/conf/ssl.crt/proxy.pem"

SSLProxyMachineCertificatePath Directive

Description: | Directory of PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificatePath directory
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the certificates and keys used for authentication of the proxy server to remote servers.

The files in this directory must be PEM-encoded and are accessed through hash filenames. Additionally, you must create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links.

Currently there is no support for encrypted private keys

Example

SSLProxyMachineCertificatePath "/usr/local/apache2/conf/proxy.crt/"

SSLProxyProtocol Directive

Description: | Configure usable SSL protocol flavors for proxy usage
Syntax: | SSLProxyProtocol [+|-]protocol ...
Default: | SSLProxyProtocol all -SSLv3 (up to 2.4.16: all)
Context: | server config, virtual host
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment for proxy . It will only connect to servers using one of the provided protocols.

Please refer to SSLProtocol for additional information.

SSLProxyVerify Directive

Description: | Type of remote server Certificate verification
Syntax: | SSLProxyVerify level
Default: | SSLProxyVerify none
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

When a proxy is configured to forward requests to a remote SSL server, this directive can be used to configure certificate verification of the remote server.

The following levels are available for level:

  • none: no remote server Certificate is required at all
  • optional: the remote server may present a valid Certificate
  • require: the remote server has to present a valid Certificate
  • optional_no_ca: the remote server may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all servers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLProxyVerify require

SSLProxyVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Remote Server Certificate verification
Syntax: | SSLProxyVerifyDepth number
Default: | SSLProxyVerifyDepth 1
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets how deeply mod_ssl should verify before deciding that the remote server does not have a valid certificate.

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 remote server certificate. A depth of 0 means that self-signed remote server certificates are accepted only, the default depth of 1 means the remote server 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 SSLProxyCACertificatePath), etc.

Example

SSLProxyVerifyDepth 10

SSLRandomSeed Directive

Description: | Pseudo Random Number Generator (PRNG) seeding source
Syntax: | SSLRandomSeed context source [bytes]
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures one or more sources for seeding the Pseudo Random Number Generator (PRNG) in OpenSSL at startup time (context is startup) and/or just before a new SSL connection is established (context is connect). This directive can only be used in the global server context because the PRNG is a global facility.

The following source variants are available:

  • builtin

    This is the always available builtin seeding source. Its 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 chosen 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.

  • file:/path/to/source

    This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified the whole file forms the entropy (and 0 is given to /path/to/source as the first argument). Use this especially at startup time, for instance with an available /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivatives like FreeBSD and Linux).

    But be careful: Usually /dev/random 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 /dev/urandom 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.

  • exec:/path/to/program

    This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of its stdout contents form the entropy. When bytes is not specified, the entirety of the data produced on stdout 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 truerand utility you can find in the mod_ssl distribution which is based on the AT&T truerand 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.

  • egd:/path/to/egd-socket (Unix only)

    This variant uses the Unix domain socket of the external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech /crypto/) to seed the PRNG. Use this if no random device exists on your platform.

Example

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

SSLRenegBufferSize Directive

Description: | Set the size for the SSL renegotiation buffer
Syntax: | SSLRenegBufferSize bytes
Default: | SSLRenegBufferSize 131072
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

If an SSL renegotiation is required in per-location context, for example, any use of SSLVerifyClient in a Directory or Location block, then mod_ssl must buffer any HTTP request body into memory until the new SSL handshake can be performed. This directive can be used to set the amount of memory that will be used for this buffer.

Note that in many configurations, the client sending the request body will be untrusted so a denial of service attack by consumption of memory must be considered when changing this configuration setting.

Example

SSLRenegBufferSize 262144

SSLRequire Directive

Description: | Allow access only when an arbitrarily complex boolean expression is true
Syntax: | SSLRequire expression
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

SSLRequire is deprecated

SSLRequire is deprecated and should in general be replaced by Require expr. The so called ap_expr syntax of Require expr is a superset of the syntax of SSLRequire, with the following exception:

In SSLRequire, the comparison operators <, <=, ... are completely equivalent to the operators lt, le, ... and work in a somewhat peculiar way that first compares the length of two strings and then the lexical order. On the other hand, ap_expr has two sets of comparison operators: The operators <, <=, ... do lexical string comparison, while the operators -lt, -le, ... do integer comparison. For the latter, there are also aliases without the leading dashes: lt, le, ...

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It is a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks.

The expression must match the following syntax (given as a BNF grammar notation):

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "in" "PeerExtList(" word ")"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

For varname any of the variables described in Environment Variables can be used. For funcname the available functions are listed in the ap_expr documentation.

The expression is parsed into an internal machine representation when the configuration is loaded, and then evaluated during request processing. In .htaccess context, the expression is both parsed and executed each time the .htaccess file is encountered during request processing.

Example

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} -ge 1 and %{TIME_WDAY} -le 5          \
            and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20       ) \
           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

The PeerExtList(object-ID) function expects to find zero or more instances of the X.509 certificate extension identified by the given object ID (OID) in the client certificate. The expression evaluates to true if the left-hand side string matches exactly against the value of an extension identified with this OID. (If multiple extensions with the same OID are present, at least one extension must match).

Example

SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")

Notes on the PeerExtList function

  • The object ID can be specified either as a descriptive name recognized by the SSL library, such as "nsComment", or as a numeric OID, such as "1.2.3.4.5.6".

  • Expressions with types known to the SSL library are rendered to a string before comparison. For an extension with a type not recognized by the SSL library, mod_ssl will parse the value if it is one of the primitive ASN.1 types UTF8String, IA5String, VisibleString, or BMPString. For an extension of one of these types, the string value will be converted to UTF-8 if necessary, then compared against the left-hand-side expression.

See also

  • Environment Variables in Apache HTTP Server, for additional examples.
  • Require expr
  • Generic expression syntax in Apache HTTP Server

SSLRequireSSL Directive

Description: | Deny access when SSL is not used for the HTTP request
Syntax: | SSLRequireSSL
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

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.

Example

SSLRequireSSL

SSLSessionCache Directive

Description: | Type of the global/inter-process SSL Session Cache
Syntax: | SSLSessionCache type
Default: | SSLSessionCache none
Context: | server config
Status: | Extension
Module: | mod_ssl

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 different pre-forked server processes. Here an inter-process cache helps to avoid unnecessary session handshakes.

The following five storage types are currently supported:

  • none

    This disables the global/inter-process Session Cache. This will incur a noticeable speed penalty and may cause problems if using certain browsers, particularly if client certificates are enabled. This setting is not recommended.

  • nonenotnull

    This disables any global/inter-process Session Cache. However it does force OpenSSL to send a non-null session ID to accommodate buggy clients that require one.

  • dbm:/path/to/datafile

    This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. This session cache may suffer reliability issues under high load. To use this, ensure that mod_socache_dbm is loaded.

  • shmcb:/path/to/datafile[(size)]

    This makes use of a high-performance cyclic buffer (approx. size bytes in size) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This is the recommended session cache. To use this, ensure that mod_socache_shmcb is loaded.

  • dc:UNIX:/path/to/socket

    This makes use of the distcache distributed session caching libraries. The argument should specify the location of the server or proxy to be used using the distcache address syntax; for example, UNIX:/path/to/socket specifies a UNIX domain socket (typically a local dc_client proxy); IP:server.example.com:9001 specifies an IP address. To use this, ensure that mod_socache_dc is loaded.

Examples

SSLSessionCache "dbm:/usr/local/apache/logs/ssl_gcache_data"
SSLSessionCache "shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)"

The ssl-cache mutex is used to serialize access to the session cache to prevent corruption. This mutex can be configured using the Mutex directive.

SSLSessionCacheTimeout Directive

Description: | Number of seconds before an SSL session expires in the Session Cache
Syntax: | SSLSessionCacheTimeout seconds
Default: | SSLSessionCacheTimeout 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Applies also to RFC 5077 TLS session resumption in Apache 2.4.10 and later

This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache, the OpenSSL internal memory cache and for sessions resumed by TLS session resumption (RFC 5077). It can be set as low as 15 for testing, but should be set to higher values like 300 in real life.

Example

SSLSessionCacheTimeout 600

SSLSessionTicketKeyFile Directive

Description: | Persistent encryption/decryption key for TLS session tickets
Syntax: | SSLSessionTicketKeyFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later

Optionally configures a secret key for encrypting and decrypting TLS session tickets, as defined in RFC 5077. Primarily suitable for clustered environments where TLS sessions information should be shared between multiple nodes. For single-instance httpd setups, it is recommended to not configure a ticket key file, but to rely on (random) keys generated by mod_ssl at startup, instead.

The ticket key file must contain 48 bytes of random data, preferrably created from a high-entropy source. On a Unix-based system, a ticket key file can be created as follows:

dd if=/dev/random of=/path/to/file.tkey bs=1 count=48

Ticket keys should be rotated (replaced) on a frequent basis, as this is the only way to invalidate an existing session ticket - OpenSSL currently doesn't allow to specify a limit for ticket lifetimes. A new ticket key only gets used after restarting the web server. All existing session tickets become invalid after a restart.

The ticket key file contains sensitive keying material and should be protected with file permissions similar to those used for SSLCertificateKeyFile.

SSLSessionTickets Directive

Description: | Enable or disable use of TLS session tickets
Syntax: | SSLSessionTickets on|off
Default: | SSLSessionTickets on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.11 and later, if using OpenSSL 0.9.8f or later.

This directive allows to enable or disable the use of TLS session tickets (RFC 5077).

TLS session tickets are enabled by default. Using them without restarting the web server with an appropriate frequency (e.g. daily) compromises perfect forward secrecy.

SSLSRPUnknownUserSeed Directive

Description: | SRP unknown user seed
Syntax: | SSLSRPUnknownUserSeed secret-string
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or later

This directive sets the seed used to fake SRP user parameters for unknown users, to avoid leaking whether a given user exists. Specify a secret string. If this directive is not used, then Apache will return the UNKNOWN_PSK_IDENTITY alert to clients who specify an unknown username.

Example

SSLSRPUnknownUserSeed "secret"

SSLSRPVerifierFile Directive

Description: | Path to SRP verifier file
Syntax: | SSLSRPVerifierFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or later

This directive enables TLS-SRP and sets the path to the OpenSSL SRP (Secure Remote Password) verifier file containing TLS-SRP usernames, verifiers, salts, and group parameters.

Example

SSLSRPVerifierFile "/path/to/file.srpv"

The verifier file can be created with the openssl command line utility:

Creating the SRP verifier file

openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username

The value given with the optional -userinfo parameter is avalable in the SSL_SRP_USERINFO request environment variable.

SSLStaplingCache Directive

Description: | Configures the OCSP stapling cache
Syntax: | SSLStaplingCache type
Context: | server config
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

Configures the cache used to store OCSP responses which get included in the TLS handshake if SSLUseStapling is enabled. Configuration of a cache is mandatory for OCSP stapling. With the exception of none and nonenotnull, the same storage types are supported as with SSLSessionCache.

SSLStaplingErrorCacheTimeout Directive

Description: | Number of seconds before expiring invalid responses in the OCSP stapling cache
Syntax: | SSLStaplingErrorCacheTimeout seconds
Default: | SSLStaplingErrorCacheTimeout 600
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

Sets the timeout in seconds before invalid responses in the OCSP stapling cache (configured through SSLStaplingCache) will expire. To set the cache timeout for valid responses, see SSLStaplingStandardCacheTimeout.

SSLStaplingFakeTryLater Directive

Description: | Synthesize "tryLater" responses for failed OCSP stapling queries
Syntax: | SSLStaplingFakeTryLater on|off
Default: | SSLStaplingFakeTryLater on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

When enabled and a query to an OCSP responder for stapling purposes fails, mod_ssl will synthesize a "tryLater" response for the client. Only effective if SSLStaplingReturnResponderErrors is also enabled.

SSLStaplingForceURL Directive

Description: | Override the OCSP responder URI specified in the certificate's AIA extension
Syntax: | SSLStaplingForceURL uri
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

This directive overrides the URI of an OCSP responder as obtained from the authorityInfoAccess (AIA) extension of the certificate. One potential use is when a proxy is used for retrieving OCSP queries.

SSLStaplingResponderTimeout Directive

Description: | Timeout for OCSP stapling queries
Syntax: | SSLStaplingResponderTimeout seconds
Default: | SSLStaplingResponderTimeout 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

This option sets the timeout for queries to OCSP responders when SSLUseStapling is enabled and mod_ssl is querying a responder for OCSP stapling purposes.

SSLStaplingResponseMaxAge Directive

Description: | Maximum allowable age for OCSP stapling responses
Syntax: | SSLStaplingResponseMaxAge seconds
Default: | SSLStaplingResponseMaxAge -1
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

This option sets the maximum allowable age ("freshness") when considering OCSP responses for stapling purposes, i.e. when SSLUseStapling is turned on. The default value (-1) does not enforce a maximum age, which means that OCSP responses are considered valid as long as their nextUpdate field is in the future.

SSLStaplingResponseTimeSkew Directive

Description: | Maximum allowable time skew for OCSP stapling response validation
Syntax: | SSLStaplingResponseTimeSkew seconds
Default: | SSLStaplingResponseTimeSkew 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

This option sets the maximum allowable time skew when mod_ssl checks the thisUpdate and nextUpdate fields of OCSP responses which get included in the TLS handshake (OCSP stapling). Only applicable if SSLUseStapling is turned on.

SSLStaplingReturnResponderErrors Directive

Description: | Pass stapling related OCSP errors on to client
Syntax: | SSLStaplingReturnResponderErrors on|off
Default: | SSLStaplingReturnResponderErrors on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

When enabled, mod_ssl will pass responses from unsuccessful stapling related OCSP queries (such as responses with an overall status other than "successful", responses with a certificate status other than "good", expired responses etc.) on to the client. If set to off, only responses indicating a certificate status of "good" will be included in the TLS handshake.

SSLStaplingStandardCacheTimeout Directive

Description: | Number of seconds before expiring responses in the OCSP stapling cache
Syntax: | SSLStaplingStandardCacheTimeout seconds
Default: | SSLStaplingStandardCacheTimeout 3600
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

Sets the timeout in seconds before responses in the OCSP stapling cache (configured through SSLStaplingCache) will expire. This directive applies to valid responses, while SSLStaplingErrorCacheTimeout is used for controlling the timeout for invalid/unavailable responses.

SSLStrictSNIVHostCheck Directive

Description: | Whether to allow non-SNI clients to access a name-based virtual host.
Syntax: | SSLStrictSNIVHostCheck on|off
Default: | SSLStrictSNIVHostCheck off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.2.12 and later

This directive sets whether a non-SNI client is allowed to access a name-based virtual host. If set to on in the default name-based virtual host, clients that are SNI unaware will not be allowed to access any virtual host, belonging to this particular IP / port combination. If set to on in any other virtual host, SNI unaware clients are not allowed to access this particular virtual host.

This option is only available if httpd was compiled against an SNI capable version of OpenSSL.

Example

SSLStrictSNIVHostCheck on

SSLUserName Directive

Description: | Variable name to determine user name
Syntax: | SSLUserName varname
Context: | server config, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets the "user" field in the Apache request object. This is used by lower modules to identify the user with a character string. In particular, this may cause the environment variable REMOTE_USER to be set. The varname can be any of the SSL environment variables.

Note that this directive has no effect if the FakeBasicAuth option is used (see SSLOptions).

Example

SSLUserName SSL_CLIENT_S_DN_CN

SSLUseStapling Directive

Description: | Enable stapling of OCSP responses in the TLS handshake
Syntax: | SSLUseStapling on|off
Default: | SSLUseStapling off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available if using OpenSSL 0.9.8h or later

This option enables OCSP stapling, as defined by the "Certificate Status Request" TLS extension specified in RFC 6066. If enabled (and requested by the client), mod_ssl will include an OCSP response for its own certificate in the TLS handshake. Configuring an SSLStaplingCache is a prerequisite for enabling OCSP stapling.

OCSP stapling relieves the client of querying the OCSP responder on its own, but it should be noted that with the RFC 6066 specification, the server's CertificateStatus reply may only include an OCSP response for a single cert. For server certificates with intermediate CA certificates in their chain (the typical case nowadays), stapling in its current implementation therefore only partially achieves the stated goal of "saving roundtrips and resources" - see also RFC 6961 (TLS Multiple Certificate Status Extension).

When OCSP stapling is enabled, the ssl-stapling mutex is used to control access to the OCSP stapling cache in order to prevent corruption, and the sss-stapling-refresh mutex is used to control refreshes of OCSP responses. These mutexes can be configured using the Mutex directive.

SSLVerifyClient Directive

Description: | Type of Client Certificate verification
Syntax: | SSLVerifyClient level
Default: | SSLVerifyClient none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

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 renegotiation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

  • none: no client Certificate is required at all
  • optional: the client may present a valid Certificate
  • require: the client has to present a valid Certificate
  • optional_no_ca: the client may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all browsers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLVerifyClient require

SSLVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Client Certificate verification
Syntax: | SSLVerifyDepth number
Default: | SSLVerifyDepth 1
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

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 renegotiation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent.

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 SSLCACertificatePath), etc.

Example

SSLVerifyDepth 10

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_status - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_status

Açıklama: | Sunucu etkinliği ve başarımı hakkında bilgi sağlar.
Durum: | Temel
Modül Betimleyici: | status_module
Kaynak Dosyası: | mod_status.c

Özet

mod_status modülü, sunucu yöneticisinin, HTTP sunucusunun ne kadar başarılı olduğu hakkında bilgi edinmesini sağlar. Bilgiler, kolayca okunabilen bir HTML sayfası olarak sunulur ve o anki sunucu istatistiklerinden oluşur. Gerekirse sayfa kendiliğinden tazelenebilir (uyumlu bir tarayıcı gerekir). Diğer sayfa o anki sunucu durumunu makine tarafından okunabilen biçimde listeler.

Sunulan bilgiler şunlardır:

  • İstekleri sunan çocuk süreç sayısı
  • Boştaki çocuk süreçlerin sayısı
  • Her çocuk sürecin durumu, çocuk sürecin işleme tabi tuttuğu istek sayısı ve sunduğu bayt sayısı (*)
  • Toplam erişim sayısı ve sunulan toplam bayt sayısı (*)
  • Sunucunun kaç kere başlatıldığı/yeniden başlatıldığı ve ne kadar zamandır çalışmakta olduğu
  • Saniyedeki ortalama istek sayısı, saniyedeki bayt sayısı ve istek başına ortalama bayt sayısı (*)
  • Birlikte tüm çocuk süreçler tarafınan toplamda ve her çocuk süreç tarafından ayrı ayrı kullanılan o anki işlemci zamanı yüzdesi (*)
  • O an işlem görmekte olan konakların ve isteklerin sayısı (*)

"(*)" imli bilgiler sadece ExtendedStatus yönergesinin değeri On olduğu takdirde mevcuttur. 2.3.6 sürümünde, bu modulün yüklenmesi öntanımlı olarak ExtendedStatus yönergesinin değerini On yapacaktır.

Durum Bilgisi Desteğinin Etkinleştirilmesi

Durum raporları, sadece example.com alanından ve sadece tarayıcılar için etkin kılınmak istenirse httpd.conf dosyasına şu satırlar eklenebilir:

<Location "/server-status">
    SetHandler server-status
    Require host example.com
</Location>

Sunucu istatistiklerine tarayıcınızla erişmek isterseniz, http://sunucunuzun.ismi.buraya/server-status şeklinde bir istek yapabilirsiniz.

Sayfanın Tazelenmesi

Tarayıcınız “tazeleme” yeteneğine sahipse durum sayfası düzenli aralıklarla güncellenecektir. Sayfanın N saniyede bir güncellenmesini isterseniz isteği şöyle yapabilirsiniz:
http://sunucunuzun.ismi.buraya/server-status?refresh=N

Makine Tarafından Okunabilen Durum Dosyası

Durum dosyasının makine tarafından okunabilen sürümüne http://sunucunuzun.ismi.buraya/server-status?auto şeklinde bir istek yaparak erişebilirsiniz. Bu, kendiliğinden çalıştığı takdirde yararlıdır; Apache HTTP Sunucusu kurulumunuzun /support dizininde bulunan log_server_status isimli Perl betiğine bakınız.

Güvenlik

mod_status sunucuya yüklendiği takdirde istatistikleri raporlama yeteneği dizin içi yapılandırma dosyaları (.htaccess gibi) dahil tüm yapılandırma dosyaları için kullanılabilir olacaktır. Bu durum güvenlik ile ilgili olarak siteniz için içinden çıkılması güç durumlara yol açabilir (çapanoğlu durumu).

Sorun gidermek için server-status kullanımı

Sunucunuzun kullanılabilir tüm özkaynakları (işlemci veya bellek) sömürdüğü ve sizin de bu soruna hangi istemcilerin veya isteklerin yol açtığını saptamak istediğiniz durumda sorunu gidermek için başlangıç yeri olarak server-status sayfası kullanılabilir.

Önce ExtendedStatus yönergesine On atadığınızsan emin olun. Böylece her çocuk süreç veya evre için tüm istek ve istemci bilgilerini görebilirsiniz.

(top veya benzeri bir süreç izleme aracı kullanarak) Artık kendi süreç listenize ana zanlılar olan süreçleri bulmak için bakabilirsiniz. Sorunun çeşidine bağlı olarak top çıktısını işlemci kullanımına veya bellek kullanımına göre sıralatabilirsiniz.

server-status sayfasını yeniden yükleyip bu süreç kimliklerine bakın. Böylece, bu süreçler tarafından hangi isteklerin hangi istemcilere sunulduğunu görebilirsiniz. İstekler kısa sürelerle görünürler, bu bakımdan iş üstünde yakalamak için çeşitli denemeler yapmanız gerekebilir.

Bu işlem, yük sorununuzdan birinci derecede sorumlu istek türleri veya istemciler hakkında bir fikir verecektir. Çoğu durumda belli bir HTTP uygulamasının yanlış davrandığını veya belli bir istemcinin sitenize saldırmakta olduğunu farkedersiniz.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_substitute - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_substitute

Description: | Perform search and replace operations on response bodies
Status: | Extension
Module Identifier: | substitute_module
Source File: | mod_substitute.c
Compatibility: | Available in Apache HTTP Server 2.2.7 and later

Summary

mod_substitute provides a mechanism to perform both regular expression and fixed string substitutions on response bodies.

Substitute Directive

Description: | Pattern to filter the response content
Syntax: | Substitute s/pattern/substitution/[infq]
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute

The Substitute directive specifies a search and replace pattern to apply to the response body.

The meaning of the pattern can be modified by using any combination of these flags:

i
Perform a case-insensitive match.
n
By default the pattern is treated as a regular expression. Using the n flag forces the pattern to be treated as a fixed string.
f
The f flag causes mod_substitute to flatten the result of a substitution allowing for later substitutions to take place on the boundary of this one. This is the default.
q
The q flag causes mod_substitute to not flatten the buckets after each substitution. This can result in much faster response and a decrease in memory utilization, but should only be used if there is no possibility that the result of one substitution will ever match a pattern or regex of a subsequent one.

Example

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    Substitute "s/foo/bar/ni"
</Location>

If either the pattern or the substitution contain a slash character then an alternative delimiter should be used:

Example of using an alternate delimiter

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    Substitute "s|<BR */?>|<br />|i"
</Location>

Backreferences can be used in the comparison and in the substitution, when regular expressions are used, as illustrated in the following example:

Example of using backreferences and captures

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    # "foo=k,bar=k" -> "foo/bar=k"
    Substitute "s|foo=(\w+),bar=\1|foo/bar=$1"
</Location>

A common use scenario for mod_substitute is the situation in which a front-end server proxies requests to a back-end server which returns HTML with hard-coded embedded URLs that refer to the back-end server. These URLs don't work for the end-user, since the back-end server is unreachable.

In this case, mod_substutite can be used to rewrite those URLs into something that will work from the front end:

Rewriting URLs embedded in proxied content

ProxyPass "/blog/" "http://internal.blog.example.com"
ProxyPassReverse "/blog/" "http://internal.blog.example.com/"

Substitute "s|http://internal.blog.example.com/|http://www.example.com/blog/|i"

ProxyPassReverse modifies any Location (redirect) headers that are sent by the back-end server, and, in this example, Substitute takes care of the rest of the problem by fixing up the HTML response as well.

SubstituteInheritBefore Directive

Description: | Change the merge order of inherited patterns
Syntax: | SubstituteInheritBefore on|off
Default: | SubstituteInheritBefore off
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute
Compatibility: | Available in httpd 2.4.17 and later

Whether to apply the inherited Substitute patterns first (on), or after the ones of the current context (off). SubstituteInheritBefore is itself inherited, hence contexts that inherit it (those that don't specify their own SubstituteInheritBefore value) will apply the closest defined merge order.

SubstituteMaxLineLength Directive

Description: | Set the maximum line size
Syntax: | SubstituteMaxLineLength bytes(b|B|k|K|m|M|g|G)
Default: | SubstituteMaxLineLength 1m
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute
Compatibility: | Available in httpd 2.4.11 and later

The maximum line size handled by mod_substitute is limited to restrict memory use. The limit can be configured using SubstituteMaxLineLength. The value can be given as the number of bytes and can be suffixed with a single letter b, B, k, K, m, M, g, G to provide the size in bytes, kilobytes, megabytes or gigabytes respectively.

Example

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    SubstituteMaxLineLength 10m
    Substitute "s/foo/bar/ni"
</Location>

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_suexec - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_suexec

Açıklama: | CGI betiklerinin belli bir kullanıcı ve grubun aidiyetinde çalışmasını mümkün kılar.
Durum: | Eklenti
Modül Betimleyici: | suexec_module
Kaynak Dosyası: | mod_suexec.c

Özet

Bu modül suexec programı ile birlikte CGI betiklerinin belli bir kullanıcı ve grubun aidiyetinde çalışmasını mümkün kılar.

Ayrıca bakınız:

  • SuEXEC Desteği

SuexecUserGroup Yönergesi

Açıklama: | CGI betiklerini çalıştıracak kullanıcı ve grup belirtilir.
Sözdizimi: | SuexecUserGroup Kullanıcı Grup
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_suexec

SuexecUserGroup yönergesi CGI programlarını çalıştıracak kullanıcı ve grubu belirtmeye yarar. CGI harici istekler hala User yönergesinde belirtilen kullanıcı tarafından yerine getirilir.

SuexecUserGroup nobody nogroup

Bu yönerge belirtildiği halde Suexec özelliği etkinleştirilmemişse Apache httpd başlatılamaz.

Ayrıca bakınız:

  • Suexec

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_unique_id - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_unique_id

Description: | Provides an environment variable with a unique identifier for each request
Status: | Extension
Module Identifier: | unique_id_module
Source File: | mod_unique_id.c

Summary

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 UNIQUE_ID is set to the identifier for each request. Unique identifiers are useful for various reasons which are beyond the scope of this document.

Theory

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.

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.

The machines in your cluster should satisfy these requirements. (Even if you have only one machine you should synchronize its clock with NTP.)

  • The machines' times are synchronized via NTP or other network time protocol.
  • 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.

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.

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. A httpd process can handle multiple requests simultaneously if you use a multi-threaded MPM. In order to identify threads, we use a thread index Apache httpd uses internally. So in order to generate unique identifiers for requests we need only distinguish between different points in time.

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 ( ip_addr, pid, time_stamp, counter ) 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.

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).

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).

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 (i.e., 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.

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).

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.

The UNIQUE_ID environment variable is constructed by encoding the 144-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, 16 bit counter, 32 bit thread index) quadruple using the alphabet [A-Za-z0-9@-] in a manner similar to MIME base64 encoding, producing 24 characters. The MIME base64 alphabet is actually [A-Za-z0-9+/] however + and / 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 UNIQUE_ID as an opaque token, which can be compared against other UNIQUE_IDs for equality only.

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 UNIQUE_IDs. 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 flag second in which all machines in the cluster stop serving any request, and stop using the old encoding format. Afterwards they can resume requests and begin issuing the new encodings.

This we believe is a relatively portable solution to this problem. 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).


mod_userdir - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_userdir

Açıklama: | Kullanıcılara özel dizinler
Durum: | Temel
Modül Betimleyici: | userdir_module
Kaynak Dosyası: | mod_userdir.c

Özet

Bu modül kullanıcılara özel dizinlere http://example.com/~kullanıcı/ sözdizimi kullanılarak erişilebilmesini mümkün kılar.

Ayrıca bakınız:

  • URL’lerin Dosya Sistemi ile Eşleştirilmesi
  • public_html eğitmeni

UserDir Yönergesi

Açıklama: | Kullanıcıya özel dizinlerin yeri
Sözdizimi: | UserDir dizin [dizin] ...
Bağlam: | sunucu geneli, sanal konak
Durum: | Temel
Modül: | mod_userdir

UserDir yönergesi, bir kullanıcıya ait bir belge için bir istek yapıldığında, isteğin kullanıcının ev dizininde bulunan belli bir dizinden karşılanmasını sağlar. dizin olarak şunlar belirtilebilir:

  • Dizinin ismi veya aşağıdakiler gibi bir kalıp.
  • disabled anahtar sözcüğü. enabled anahtar sözcüğü ile sonradan etkin kılınmadıkça tüm kullanıcı-dizin dönüşümlerini iptal eder (aşağıya bakınız).
  • disabled anahtar sözcüğünü takibeden boşluk ayraçlı kullanıcı isimleri listesi. Bu listede yer alan kullanıcı isimlerine, sonradan bir enabled listesinde görünse bile, dizin dönüşümleri asla uygulanmaz.
  • enabled anahtar sözcüğünü takibeden boşluk ayraçlı kullanıcı isimleri listesi. Genel bir iptal sözkonusu olsa bile, kullanıcı ismi bir disabled listesinde yer almadıkça, bu listede yer alan dizinlere dönüşüm uygulanır.

Userdir yönergesinde ne enabled ne de disabled varsa, argüman bir dosya ismi kalıbı olarak ele alınır ve kullanıcı belge kök dizininin yolunu oluşturmakta kullanılır. http://example.com/~ali/bir/iki.html şöyle dönüştürülür:

Kullanılan UserDir yönergesi | Elde edilen yol
UserDir public_html | ~ali/public_html/bir/iki.html
UserDir /usr/siteler | /usr/siteler/ali/bir/iki.html
UserDir /home/*/htdocs | /home/ali/htdocs/bir/iki.html

Aşağıdaki yönergelerle istemciye gönderilecek yönlendirmeler:

Kullanılan UserDir yönergesi | Elde edilen yönlendirme
UserDir http://example.com/users | http://example.com/users/ali/bir/iki.html
UserDir http://example.com/*/usr | http://example.com/ali/usr/bir/iki.html
UserDir http://example.com/~*/ | http://example.com/~ali/bir/iki.html
Bu yönergeyi kullanırken dikkatli olun; örneğin, "UserDir ./" şeklinde bir atama "/~root" isteklerini "/" dizinine yönlendirir ki bu elbette istenmez. Bu bakımdan yapılandırmanızda mutlaka bir "UserDir disabled root" satırının yer almasını tavsiye ederiz. Daha fazla bilgi için Directory yönergesine ve Güvenlik İpuçları sayfasına bakınız.

Diğer örnekler:

Bir kaç kullanıcı hariç kalan herkesin UserDir dizinlerini iptal etmek için şunu yapabilirsiniz:

UserDir disabled
UserDir enabled birey1 birey2 birey3

Bir kaç kullanıcı hariç kalan herkesin UserDir dizinlerini etkin kılmak için şunu yapabilirsiniz:

UserDir disabled birey4 birey5 birey6

Birden fazla dizin belirtmek de mümkündür:

Userdir public_html /usr/siteler http://example.com/

Bu örneğe göre, http://example.com/~ali/bir/iki.html şeklinde bir istek alındığında sunucu önce http://example.com/~ali/bir/iki.html yönlendirmesini deneyecektir. Onu bulamazsa isteği /usr/siteler/ali/bir/iki.html dosyasını arayacak onu da bulamazsa istemciyi http://example.com/ali/bir/iki.html adresine yönlendirecektir.

Argüman listesine bir yönlendirme ekleyecekseniz, bu, listenin son elemanı olmalıdır. Apache httpd yönlendirmenin başarılı sonuç verip vermediğini bilemeyecektir. Bu bakımdan, listede bu yönlendirmeden sonra bir yönlendirme daha bulunması daha iyi olacaktır.

Kullanıcı dizini dönüşümü Apache 2.1.4 sürümü ve sonrasında öntanımlı olarak etkin değildir. Daha önceki sürümlerde bir UserDir yönergesinin yokluğunda UserDir public_html öntanımlıydı.

Ayrıntıların birleştirilmesi

Etkinleştirilen ve etkisizleştirilen kullanıcılara özgü listeler küresel etki alanından sanal konak etki alanına aktarılırken yer değiştirme yapılır, mevcutla birleştirilmez.

Ayrıca bakınız:

  • Kullanıcı Dizinleri

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_usertrack - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_usertrack

Description: | Clickstream logging of user activity on a site
Status: | Extension
Module Identifier: | usertrack_module
Source File: | mod_usertrack.c

Summary

Provides tracking of a user through your website via browser cookies.

Logging

mod_usertrack sets a cookie which can be logged via mod_log_config configurable logging formats:

LogFormat "%{Apache}n %r %t" usertrack
CustomLog logs/clickstream.log usertrack

CookieDomain Directive

Description: | The domain to which the tracking cookie applies
Syntax: | CookieDomain domain
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

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.

The domain string must begin with a dot, and must include at least one embedded dot. That is, .example.com is legal, but www.example.com and .com are not.

Most browsers in use today will not allow cookies to be set for a two-part top level domain, such as .co.uk, although such a domain ostensibly fulfills the requirements above.
These domains are equivalent to top level domains such as .com, and allowing such cookies may be a security risk. Thus, if you are under a two-part top level domain, you should still use your actual domain, as you would with any other top level domain (for example .example.co.uk).
CookieDomain .example.com

CookieExpires Directive

Description: | Expiry time for the tracking cookie
Syntax: | CookieExpires expiry-period
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When used, this directive sets an expiry time on the cookie generated by the usertrack module. The expiry-period 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, days, 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.

If this directive is not used, cookies last only for the current browser session.

CookieExpires "3 weeks"

CookieName Directive

Description: | Name of the tracking cookie
Syntax: | CookieName token
Default: | CookieName Apache
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive allows you to change the name of the cookie this module uses for its tracking purposes. By default the cookie is named "Apache".

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 "-".

CookieName clicktrack

CookieStyle Directive

Description: | Format of the cookie header field
Syntax: | CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965
Default: | CookieStyle Netscape
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive controls the format of the cookie header field. The three formats allowed are:

  • Netscape, which is the original but now deprecated syntax. This is the default, and the syntax Apache has historically used.
  • Cookie or RFC2109, which is the syntax that superseded the Netscape syntax.
  • Cookie2 or RFC2965, which is the most current cookie syntax.

Not all clients can understand all of these formats, but you should use the newest one that is generally acceptable to your users' browsers. At the time of writing, most browsers support all three of these formats, with Cookie2 being the preferred format.

CookieStyle Cookie2

CookieTracking Directive

Description: | Enables tracking cookie
Syntax: | CookieTracking on|off
Default: | CookieTracking off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When mod_usertrack is loaded, and CookieTracking on is set, Apache will send 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, enabling mod_usertrack will not activate cookies.

CookieTracking on

Copyright 2016 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_version - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_version

Description: | Version dependent configuration
Status: | Extension
Module Identifier: | version_module
Source File: | mod_version.c

Summary

This module is designed for the use in test suites and large networks which have to deal with different httpd versions and different configurations. It provides a new container -- <IfVersion>, which allows a flexible version checking including numeric comparisons and regular expressions.

Examples

<IfVersion 2.4.2>
    # current httpd version is exactly 2.4.2
</IfVersion>

<IfVersion >= 2.5>
    # use really new features :-)
</IfVersion>

See below for further possibilities.

<IfVersion> Directive

Description: | contains version dependent configuration
Syntax: | <IfVersion [[!]operator] version> ... </IfVersion>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Extension
Module: | mod_version

The <IfVersion> section encloses configuration directives which are executed only if the httpd version matches the desired criteria. For normal (numeric) comparisons the version argument has the format major[.minor[.patch]], e.g. 2.1.0 or 2.2. minor and patch are optional. If these numbers are omitted, they are assumed to be zero. The following numerical operators are possible:

operator | description
= or == | httpd version is equal
> | httpd version is greater than
>= | httpd version is greater or equal
< | httpd version is less than
<= | httpd version is less or equal

Example

<IfVersion >= 2.3>
    # this happens only in versions greater or
    # equal 2.3.0.
</IfVersion>

Besides the numerical comparison it is possible to match a regular expression against the httpd version. There are two ways to write it:

operator | description
= or == | version has the form /regex/
~ | version has the form regex

Example

<IfVersion = /^2.4.[01234]$/>
    # e.g. workaround for buggy versions
</IfVersion>

In order to reverse the meaning, all operators can be preceded by an exclamation mark (!):

<IfVersion !~ ^2.4.[01234]$>
    # not for those versions
</IfVersion>

If the operator is omitted, it is assumed to be =.


mod_vhost_alias - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Apache Modülü mod_vhost_alias

Açıklama: | Kitlesel sanal konakların devingen olarak yapılandırılmasını sağlar
Durum: | Eklenti
Modül Betimleyici: | vhost_alias_module
Kaynak Dosyası: | mod_vhost_alias.c

Özet

Bu modül, hangi dosyaların sunulacağını saptamak için dosya yolunun parçası olarak HTTP isteğinin Host: başlığının ve/veya IP adresinin kullanılmasını mümkün kılarak devingen yapılandırmalı sanal konaklar oluşturur. Böylece benzer yapılandırmaya sahip çok büyük sayıda sanal konak kullanımı kolaşlaşır.

Bilginize

URI’leri dosya isimlerine dönüştürmek için mod_alias veya mod_userdir kullanılmışsa bunlar mod_vhost_alias yönergeleri tarafından aşağıda açıklandığı gibi geçersiz kılınırlar. Örneğin, aşağıdaki yapılandırma her durumda /cgi-bin/script.pl betiğini /usr/local/apache2/cgi-bin/script.pl betiğine eşleyecektir:

ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"
VirtualScriptAlias "/nerede/bilinmiyor/%0/cgi-bin/"

Ayrıca bakınız:

  • UseCanonicalName
  • Devingen olarak Yapılandırılan Kitlesel Sanal Barındırma

Dizin İsimlerinin Elde Edilmesi

Bu modüldeki tüm yönergeler bir dizgeyi bir dosya yoluna dönüştürerek çalışırlar. Dönüşüm dizgesi (bundan sonra “isim” diyeceğiz) ya sunucu ismi olur (bunun nasıl belirlendiğini öğrenmek için UseCanonicalName yönergesine bakınız) ya da sunucu üzerindeki sanal konağın IP adresi olur. Dönüşümü, printf’inkilerin benzeri birkaç biçem belirteci denetler:

%% | Bir % imi yerleştirir.
%p | Sanal konağın IP adresini yerleştirir.
%N.M | İsmin parçalarını yerleştirir.

N ve M ismin alt dizgelerini belirtmek için kullanılır. N, ismin noktalarla ayrılmış bileşenlerinden seçim yaparken M, N ile seçilen parçadan karakter seçmekte kullanılır. M isteğe bağlı olup mevcut olmaması halinde öntanımlı olarak sıfırdır. Noktanın varlığı M’nin varlığına bağlıdır. Dönüşüm şöyle uygulanır:

0 | ismin tamamı
1 | ilk parça
2 | ikinci parça
-1 | son parça
-2 | sondan bir önceki parça
2+ | ikinci parça ve sonraki parçaların hepsi
-2+ | sondan bir önceki parça ve daha önceki parçaların hepsi
1+ ve -1+ | 0 ile aynı

N veya M parça sayısından büyükse dönüşüm dizgesi sadece alt çizgi karakterini içerir.

Örnekler

Sunucu yapılandırma dosyanızda isme dayalı sanal konaklar için aşağıdaki yönergeler kullanılıyor olsun:

UseCanonicalName    Off
VirtualDocumentRoot "/usr/local/apache/sankonlar/%0"

http://example.com/dizin/dosya.html için yapılan bir istek /usr/local/apache/sankonlar/example.com/dizin/dosya.html dosyası ile yerine getirilecektir.

Çok büyük sayıda sanal konak için sankonlar dizininin boyutlarını küçük tutmak amacıyla dosyalar düzenlenebilir. Bunu yapılandırma dosyanızda şöyle yapabilirsiniz:

UseCanonicalName    Off
VirtualDocumentRoot "/usr/local/apache/sankonlar/%3+/%2.1/%2.2/%2.3/%2"

http://falan.filan.example.com/dizin/dosya.html için yapılan bir istek /usr/local/apache/sankonlar/example.com/f/i/l/filan/dizin/dosya.html ile yerine getirilecektir.

Bu sefer de parçaları ismin sonundan toplayalım:

VirtualDocumentRoot "/usr/local/apache/sankonlar/%3+/%2.-1/%2.-2/%2.-3/%2"

Bu durumda istek /usr/local/apache/sankonlar/example.com/n/a/l/filan/dizin/dosya.html ile karşılanırdı.

Şöyle bir şey de yapabilirsiniz:

VirtualDocumentRoot "/usr/local/apache/sankonlar/%3+/%2.1/%2.2/%2.3/%2.4+"

Bu örnek için istek /usr/local/apache/sankonlar/example.com/f/i/l/an/dizin/dosya.html dosyasından karşılanırdı.

Kullanıcıların çoğunun ortak isteği, istenen konak adının uzunluğu veya sayısı için endişelenmeksizin çok sayıda belge köküne çok sayıda alan adından erişilebilmesidir. Eğer istenen konak adı www.domain.example.com değil de sub.www.domain.example.com ise %3+ kullanımı, belge kök dizininin düşünüldüğü gibi example.com değil /usr/local/apache/vhosts/domain.example.com/... olmasını sağlar. Böyle durumlarda, daima alan adı ve tld ile sonuçlanan %-2.0.%-1.0 birleşiminin kullanımı daha yararlı olabilir. Böylece, tüm ilk, ikinci ve üçüncü seviye alt alan adlarını aynı dizine yönlendirecek bir yapılandırma yapılabilir:

VirtualDocumentRoot "/usr/local/apache/vhosts/%-2.0.%-1.0"

Yukarıdaki örnekte, example.com, www.example.com ve hatta www.sub.example.com bile /usr/local/apache/vhosts/example.com dizinine yönlendirilecektir.

IP’ye dayalı sanal konaklar için yapılandırma dosyanızda şu satırlar olabilirdi:

UseCanonicalName DNS
VirtualDocumentRootIP "/usr/local/apache/sankonlar/%1/%2/%3/%4/belgeler"
VirtualScriptAliasIP  "/usr/local/apache/sankonlar/%1/%2/%3/%4/cgi-bin"

http://falan.filan.example.com/dizin/dosya.html için yapılan bir istek eğer falan.filan.example.com’un IP adresi 10.20.30.40 olsaydı, /usr/local/apache/sankonlar/10/20/30/40/belgeler/dizin/dosya.html dosyası ile karşılanırdı. http://falan.filan.example.com/cgi-bin/betik.pl için yapılan bir istek ise /usr/local/apache/sankonlar/10/20/30/40/cgi-bin/betik.pl betiğinin çalıştırılması ile sağlanırdı.

Bir VirtualDocumentRoot yönergesinin . karakterini içermesini isterseniz, bir biçem belirteci ile karışıklığa sebep olmaksızın bunu şöyle sağlayabilirsiniz:

VirtualDocumentRoot "/usr/local/apache/sankonlar/%2.0.%3.0"

Bu durumda http://falan.filan.example.com/dizin/dosya.html için yapılan bir istek /usr/local/apache/sankonlar/filan.mesela/dizin/dosya.html dosyası ile karşılanacaktır.

LogFormat yönergesinin %V ve %A biçem belirteçleri bu modülle birlikte kullanıldığında çok yararlı olurlar.

VirtualDocumentRoot Yönergesi

Açıklama: | Bir sanal konağın belge kök dizinini devingen olarak yapılandırır.
Sözdizimi: | VirtualDocumentRoot hesaplanan-dizin|none
Öntanımlı: | VirtualDocumentRoot none
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_vhost_alias

VirtualDocumentRoot yönergesi sunucu ismine göre belgelerin bulunacağı yeri Apache HTTP Sunucusunun saptamasını sağlar. hesaplanan-dizin’in dönüşüm sonucu DocumentRoot yönergesinin değeriymiş gibi belge ağacının kök dizini olarak kullanılır. hesaplanan-dizin yerine none belirtilmişse VirtualDocumentRoot iptal edilmiş olur. Bu yönerge VirtualDocumentRootIP yönergesinin kullanıldığı bağlamda yer alamaz.

Bilginize

VirtualDocumentRoot yönergesi aynı bağlamda veya alt bağlamlarda da kullanılabilen DocumentRoot yönergelerini geçersiz kılar. Genel sunucu etki alanına bir VirtualDocumentRoot konulması, daha sonra yer alan her sanal konak tanımı içinde VirtualDocumentRoot yönergesine None atamadıkça bu sanal konaklarda yapılmış DocumentRoot atamalarını geçersiz kılacaktır.

VirtualDocumentRootIP Yönergesi

Açıklama: | Bir sanal konağın belge kök dizinini devingen olarak yapılandırır.
Sözdizimi: | VirtualDocumentRootIP hesaplanan-dizin|none
Öntanımlı: | VirtualDocumentRootIP none
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_vhost_alias

VirtualDocumentRootIP yönergesi, dizinin saptanmasında sunucu ismi yerine bağlantının sonlandığı sunucunun IP adresini kullanması dışında VirtualDocumentRoot gibidir.

VirtualScriptAlias Yönergesi

Açıklama: | Bir sanal konağın CGI dizinini devingen olarak yapılandırır.
Sözdizimi: | VirtualScriptAlias hesaplanan-dizin|none
Öntanımlı: | VirtualScriptAlias none
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_vhost_alias

VirtualScriptAlias yönergesi, CGI betiklerinin bulunacağı yeri Apache httpd’nin saptamasını sağlamak bakımından VirtualDocumentRoot yönergesinin yaptığını yapar. /cgi-bin/ ile başlayan istekler için ise ScriptAlias yönergesinin yaptığını yapar.

VirtualScriptAliasIP Yönergesi

Açıklama: | Bir sanal konağın CGI dizinini devingen olarak yapılandırır.
Sözdizimi: | VirtualScriptAliasIP hesaplanan-dizin|none
Öntanımlı: | VirtualScriptAliasIP none
Bağlam: | sunucu geneli, sanal konak
Durum: | Eklenti
Modül: | mod_vhost_alias

VirtualScriptAliasIP yönergesi, dizinin saptanmasında sunucu ismi yerine bağlantının sonlandığı sunucunun IP adresini kullanması dışında VirtualScriptAlias gibidir.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


mod_watchdog - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_watchdog

Description: | provides infrastructure for other modules to periodically run tasks
Status: | Base
Module Identifier: | watchdog_module
Source File: | mod_watchdog.c
Compatibility: | Available in Apache 2.3 and later

Summary

mod_watchdog defines programmatic hooks for other modules to periodically run tasks. These modules can register handlers for mod_watchdog hooks. Currently, the following modules in the Apache distribution use this functionality:

  • mod_heartbeat
  • mod_heartmonitor
To allow a module to use mod_watchdog functionality, mod_watchdog itself must be statically linked to the server core or, if a dynamic module, be loaded before the calling module.

WatchdogInterval Directive

Description: | Watchdog interval in seconds
Syntax: | WatchdogInterval number-of-seconds
Default: | WatchdogInterval 1
Context: | server config
Status: | Base
Module: | mod_watchdog

Sets the interval at which the watchdog_step hook runs. Default is to run every second.


mod_xml2enc - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_xml2enc

Description: | Enhanced charset/internationalisation support for libxml2-based filter modules
Status: | Base
Module Identifier: | xml2enc_module
Source File: | mod_xml2enc.c
Compatibility: | Version 2.4 and later. Available as a third-party module for 2.2.x versions

Summary

This module provides enhanced internationalisation support for markup-aware filter modules such as mod_proxy_html. It can automatically detect the encoding of input data and ensure they are correctly processed by the libxml2 parser, including converting to Unicode (UTF-8) where necessary. It can also convert data to an encoding of choice after markup processing, and will ensure the correct charset value is set in the HTTP Content-Type header.

Usage

There are two usage scenarios: with modules programmed to work with mod_xml2enc, and with those that are not aware of it:

Filter modules enabled for mod_xml2enc

Modules such as mod_proxy_html version 3.1 and up use the xml2enc_charset optional function to retrieve the charset argument to pass to the libxml2 parser, and may use the xml2enc_filter optional function to postprocess to another encoding. Using mod_xml2enc with an enabled module, no configuration is necessary: the other module will configure mod_xml2enc for you (though you may still want to customise it using the configuration directives below).

Non-enabled modules

To use it with a libxml2-based module that isn't explicitly enabled for mod_xml2enc, you will have to configure the filter chain yourself. So to use it with a filter foo provided by a module mod_foo to improve the latter's i18n support with HTML and XML, you could use

    FilterProvider iconv    xml2enc Content-Type $text/html
    FilterProvider iconv    xml2enc Content-Type $xml
    FilterProvider markup   foo Content-Type $text/html
    FilterProvider markup   foo Content-Type $xml
    FilterChain     iconv markup

mod_foo will now support any character set supported by either (or both) of libxml2 or apr_xlate/iconv.

Programming API

Programmers writing libxml2-based filter modules are encouraged to enable them for mod_xml2enc, to provide strong i18n support for your users without reinventing the wheel. The programming API is exposed in mod_xml2enc.h, and a usage example is mod_proxy_html.

Detecting an Encoding

Unlike mod_charset_lite, mod_xml2enc is designed to work with data whose encoding cannot be known in advance and thus configured. It therefore uses 'sniffing' techniques to detect the encoding of HTTP data as follows:

  1. If the HTTP Content-Type header includes a charset parameter, that is used.
  2. If the data start with an XML Byte Order Mark (BOM) or an XML encoding declaration, that is used.
  3. If an encoding is declared in an HTML <META> element, that is used.
  4. If none of the above match, the default value set by xml2EncDefault is used.

The rules are applied in order. As soon as a match is found, it is used and detection is stopped.

Output Encoding

libxml2 always uses UTF-8 (Unicode) internally, and libxml2-based filter modules will output that by default. mod_xml2enc can change the output encoding through the API, but there is currently no way to configure that directly.

Changing the output encoding should (in theory, at least) never be necessary, and is not recommended due to the extra processing load on the server of an unnecessary conversion.

Unsupported Encodings

If you are working with encodings that are not supported by any of the conversion methods available on your platform, you can still alias them to a supported encoding using xml2EncAlias.

xml2EncAlias Directive

Description: | Recognise Aliases for encoding values
Syntax: | xml2EncAlias charset alias [alias ...]
Context: | server config
Status: | Base
Module: | mod_xml2enc

This server-wide directive aliases one or more encoding to another encoding. This enables encodings not recognised by libxml2 to be handled internally by libxml2's encoding support using the translation table for a recognised encoding. This serves two purposes: to support character sets (or names) not recognised either by libxml2 or iconv, and to skip conversion for an encoding where it is known to be unnecessary.

xml2EncDefault Directive

Description: | Sets a default encoding to assume when absolutely no information can be automatically detected
Syntax: | xml2EncDefault name
Context: | server config, virtual host, directory, .htaccess
Status: | Base
Module: | mod_xml2enc
Compatibility: | Version 2.4.0 and later; available as a third-party module for earlier versions.

If you are processing data with known encoding but no encoding information, you can set this default to help mod_xml2enc process the data correctly. For example, to work with the default value of Latin1 (iso-8859-1 specified in HTTP/1.0, use

xml2EncDefault iso-8859-1

xml2StartParse Directive

Description: | Advise the parser to skip leading junk.
Syntax: | xml2StartParse element [element ...]
Context: | server config, virtual host, directory, .htaccess
Status: | Base
Module: | mod_xml2enc

Specify that the markup parser should start at the first instance of any of the elements specified. This can be used as a workaround where a broken backend inserts leading junk that messes up the parser (example here).

It should never be used for XML, nor well-formed HTML.


Developer Documentation for the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Developer Documentation for the Apache HTTP Server 2.4

Warning

Many of the documents listed here are in need of update. They are in different stages of progress. Please be patient and follow this link to propose a fix or point out any error/discrepancy.

2.4 development documents

  • Developing modules for the Apache HTTP Server 2.4
  • Hook Functions in 2.4
  • Request Processing in 2.4
  • How filters work in 2.4
  • Guidelines for output filters in 2.4
  • Documenting code in 2.4
  • Thread Safety Issues in 2.4

Upgrading to 2.4

  • API changes in 2.3/2.4
  • Converting Modules from 1.3 to 2.x

External Resources

  • Autogenerated Apache HTTP Server (trunk) code documentation (the link is built by this job).
  • Developer articles at apachetutor include:
    • Request Processing
    • Configuration for Modules
    • Resource Management
    • Connection Pooling
    • Introduction to Buckets and Brigades


Apache 1.3 API notes - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Apache 1.3 API notes

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.

These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do).

A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete -- the real ones have more slots that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge.

Finally, here's an outline, to give you some bare idea of what's coming up, and in what order:

  • Basic concepts.
    • Handlers, Modules, and Requests
    • A brief tour of a module
  • How handlers work
    • A brief tour of the request_rec
    • Where request_rec structures come from
    • Handling requests, declining, and returning error codes
    • Special considerations for response handlers
    • Special considerations for authentication handlers
    • Special considerations for logging handlers
  • Resource allocation and resource pools
  • Configuration, commands and the like
    • Per-directory configuration structures
    • Command handling
    • Side notes --- per-server configuration, virtual servers, etc.

Basic concepts

We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.

Handlers, Modules, and Requests

Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are:

  • URI -> Filename translation
  • Auth ID checking [is the user who they say they are?]
  • Auth access checking [is the user authorized here?]
  • Access checking other than auth
  • Determining MIME type of the object requested
  • `Fixups' -- there aren't any of these yet, but the phase is intended as a hook for possible extensions like SetEnv, which don't really fit well elsewhere.
  • Actually sending a response back to the client.
  • Logging the request

These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things:

  • Handle the request, and indicate that it has done so by returning the magic constant OK.
  • Decline to handle the request, by returning the magic integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there.
  • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case.

Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication checking, all handlers always run (barring an error). Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined).

The handlers themselves are functions of one argument (a request_rec structure. vide infra), which returns an integer, as above.

A brief tour of a module

At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module -- this handles both CGI scripts and the ScriptAlias config file command. It's actually a great deal more complicated than most modules, but if we're going to have only one example, it might as well be the one with its fingers in every place.

Let's begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of ScriptAlias, it also has handlers for the name translation phase (to recognize ScriptAliased URIs), the type-checking phase (any ScriptAliased request is typed as a CGI script).

The module needs to maintain some per (virtual) server information, namely, the ScriptAliases in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have ScriptAliases declared).

Finally, this module contains code to handle the ScriptAlias command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked.

A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself. That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd_parms structure contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as ScriptAlias). With no further ado, the module itself:

        /* Declarations of handlers. */

int translate_scriptalias (request_rec *);
int type_scriptalias (request_rec *);
int cgi_handler (request_rec *);

/* Subsidiary dispatch table for response-phase
* handlers, by MIME type */

handler_rec cgi_handlers[] = {
{ "application/x-httpd-cgi", cgi_handler },
{ NULL }
};

/* Declarations of routines to manipulate the
* module's configuration info.  Note that these are
* returned, and passed in, as void *'s; the server
* core keeps track of them, but it doesn't, and can't,
* know their internal structure.
*/

void *make_cgi_server_config (pool *);
void *merge_cgi_server_config (pool *, void *, void *);

/* Declarations of routines to handle config-file commands */

extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
                                  char *real);

command_rec cgi_cmds[] = {
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
"a fakename and a realname"},
{ NULL }
};

module cgi_module = {

  STANDARD_MODULE_STUFF,
  NULL,                     /* initializer */
  NULL,                     /* dir config creator */
  NULL,                     /* dir merger */
  make_cgi_server_config,   /* server config */
  merge_cgi_server_config,  /* merge server config */
  cgi_cmds,                 /* command table */
  cgi_handlers,             /* handlers */
  translate_scriptalias,    /* filename translation */
  NULL,                     /* check_user_id */
  NULL,                     /* check auth */
  NULL,                     /* check access */
  type_scriptalias,         /* type_checker */
  NULL,                     /* fixups */
  NULL,                     /* logger */
  NULL                      /* header parser */
};

How handlers work

The sole argument to handlers is a request_rec structure. This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request_rec structure.

A brief tour of the request_rec

The request_rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself.

The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively).

Other commonly used data items are tables giving the MIME headers on the client's original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the ap_table_get and ap_table_set routines.

Note that the Content-type header value cannot be set by module content-handlers using the ap_table_*() routines. Rather, it is set by pointing the content_type field in the request_rec structure to an appropriate string. e.g.,

r->content_type = "text/html";

Finally, there are pointers to two data structures which, in turn, point to per-module configuration structures. Specifically, these hold pointers to the data structures which the module has built to describe the way it has been configured to operate in a given directory (via .htaccess files or <Directory> sections), for private data it has built in the course of servicing the request (so modules' handlers for one phase can pass `notes' to their handlers for other phases). There is another such configuration vector in the server_rec data structure pointed to by the request_rec, which contains per (virtual) server configuration data.

Here is an abridged declaration, giving the fields most commonly used:

struct request_rec {

pool *pool;
conn_rec *connection;
server_rec *server;

/* What object is being requested */

char *uri;
char *filename;
char *path_info;

char *args;           /* QUERY_ARGS, if any */
struct stat finfo;    /* Set by server core;
                       * st_mode set to zero if no such file */

char *content_type;
char *content_encoding;

/* MIME header environments, in and out. Also,
 * an array containing environment variables to
 * be passed to subprocesses, so people can write
 * modules to add to that environment.
 *
 * The difference between headers_out and
 * err_headers_out is that the latter are printed
 * even on error, and persist across internal
 * redirects (so the headers printed for
 * ErrorDocument handlers will have them).
 */

table *headers_in;
table *headers_out;
table *err_headers_out;
table *subprocess_env;

/* Info about the request itself... */

int header_only;     /* HEAD request, as opposed to GET */
char *protocol;      /* Protocol, as given to us, or HTTP/0.9 */
char *method;        /* GET, HEAD, POST, etc. */
int method_number;   /* M_GET, M_POST, etc. */

/* Info for logging */

char *the_request;
int bytes_sent;

/* A flag which modules can set, to indicate that
 * the data being returned is volatile, and clients
 * should be told not to cache it.
 */

int no_cache;

/* Various other config info which may change
 * with .htaccess files
 * These are config vectors, with one void*
 * pointer for each module (the thing pointed
 * to being the module's business).
 */

void *per_dir_config;   /* Options set in config files, etc. */
void *request_config;   /* Notes on *this* request */

};

Where request_rec structures come from

Most request_rec structures are built by reading an HTTP request from a client, and filling in the fields. However, there are a few exceptions:

  • If the request is to an imagemap, a type map (i.e., a *.var file), or a CGI script which returned a local `Location:', then the resource which the user requested is going to be ultimately located by some URI other than what the client originally supplied. In this case, the server does an internal redirect, constructing a new request_rec for the new URI, and processing it almost exactly as if the client had requested the new URI directly.
  • If some handler signaled an error, and an ErrorDocument is in scope, the same internal redirect machinery comes into play.

  • Finally, a handler occasionally needs to investigate `what would happen if' some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use.

    Such handlers can construct a sub-request, using the functions ap_sub_req_lookup_file, ap_sub_req_lookup_uri, and ap_sub_req_method_uri; these construct a new request_rec structure and processes it as you would expect, up to but not including the point of actually sending a response. (These functions skip over the access checks if the sub-request is for a file in the same directory as the original request).

    (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the function ap_run_sub_req).

Handling requests, declining, and returning error codes

As discussed above, each handler, when invoked to handle a particular request_rec, has to return an int to indicate what happened. That can either be

  • OK -- the request was handled successfully. This may or may not terminate the phase.
  • DECLINED -- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another.
  • an HTTP error code, which aborts handling of the request.

Note that if the error code returned is REDIRECT, then the module should put a Location in the request's headers_out, to indicate where the client should be redirected to.

Special considerations for response handlers

Handlers for most phases do their work by simply setting a few fields in the request_rec structure (or, in the case of access checkers, simply by returning the correct error code). However, response handlers have to actually send a request back to the client.

They should begin by sending an HTTP response header, using the function ap_send_http_header. (You don't have to do anything special to skip sending the header for HTTP/0.9 requests; the function figures out on its own that it shouldn't do anything). If the request is marked header_only, that's all they should do; they should return after that, without attempting any further output.

Otherwise, they should produce a request body which responds to the client as appropriate. The primitives for this are ap_rputc and ap_rprintf, for internally generated output, and ap_send_fd, to copy the contents of some FILE * straight to the client.

At this point, you should more or less understand the following piece of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it's desirable to do so in a particular response handler -- ap_set_last_modified checks against the If-modified-since value supplied by the client, if any, and returns an appropriate code (which will, if nonzero, be USE_LOCAL_COPY). No similar considerations apply for ap_set_content_length, but it returns an error code for symmetry.

        int default_handler (request_rec *r)
{
int errstatus;
FILE *f;

if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;

if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
||
             (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;

f = fopen (r->filename, "r");

if (f == NULL) {
log_reason("file permissions deny server access", r->filename, r);
return FORBIDDEN;
}

register_timeout ("send", r);
ap_send_http_header (r);

if (!r->header_only) send_fd (f, r);
ap_pfclose (r->pool, f);
return OK;
}

Finally, if all of this is too much of a challenge, there are a few ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking ap_internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK.

(Invoking ap_internal_redirect from handlers which are not response handlers will lead to serious confusion).

Special considerations for authentication handlers

Stuff that should be discussed here in detail:

  • Authentication-phase handlers not invoked unless auth is configured for the directory.
  • Common auth configuration stored in the core per-dir configuration; it has accessors ap_auth_type, ap_auth_name, and ap_requires.
  • Common routines, to handle the protocol end of things, at least for HTTP basic authentication (ap_get_basic_auth_pw, which sets the connection->user structure field automatically, and ap_note_basic_auth_failure, which arranges for the proper WWW-Authenticate: header to be sent back).

Special considerations for logging handlers

When a request has internally redirected, there is the question of what to log. Apache handles this by bundling the entire chain of redirects into a list of request_rec structures which are threaded through the r->prev and r->next pointers. The request_rec which is passed to the logging handlers in such cases is the one which was originally built for the initial request from the client; note that the bytes_sent field will only be correct in the last request in the chain (the one for which a response was actually sent).

Resource allocation and resource pools

One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them.

The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question.

When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked.

Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse.

It should be noted that use of the pool machinery isn't generally obligatory, except for situations like logging handlers, where you really need to register cleanups to make sure that the log file gets closed when the server restarts (this is most easily done by using the function ap_pfopen, which also arranges for the underlying file descriptor to be closed before any child processes, such as for CGI scripts, are execed), or in case you are using the timeout machinery (which isn't yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory allocation, ap_palloc is generally faster than malloc.

We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery.

Allocation of memory in pools

Memory is allocated to pools by calling the function ap_palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). Within handlers for handling requests, the most common way of getting a resource pool structure is by looking at the pool slot of the relevant request_rec; hence the repeated appearance of the following idiom in module code:

int my_handler(request_rec *r)
{
struct my_structure *foo;
...

foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
 }

Note that there is no ap_pfree -- ap_palloced memory is freed only when the associated resource pool is cleared. This means that ap_palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check.

(It also raises the possibility that heavy use of ap_palloc could cause a server process to grow excessively large. There are two ways to deal with this, which are dealt with below; briefly, you can use malloc, and try to be sure that all of the memory gets explicitly freed, or you can allocate a sub-pool of the main pool, allocate your memory in the sub-pool, and clear it out periodically. The latter technique is discussed in the section on sub-pools below, and is used in the directory-indexing code, in order to avoid excessive storage allocation when listing directories with thousands of files).

Allocating initialized memory

There are functions which allocate initialized memory, and are frequently useful. The function ap_pcalloc has the same interface as ap_palloc, but clears out the memory it allocates before it returns it. The function ap_pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, returning a pointer to the copy. Finally ap_pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance:

ap_pstrcat (r->pool, "foo", "/", "bar", NULL);

returns a pointer to 8 bytes worth of memory, initialized to "foo/bar".

Commonly-used pools in the Apache Web server

A pool is really defined by its lifetime more than anything else. There are some static pools in http_main which are passed to various non-http_main functions as arguments at opportune times. Here they are:

permanent_pool
never passed to anything else, this is the ancestor of all pools
pconf
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the server is terminated or restarts; passed to all config-time routines, either via cmd->pool, or as the "pool *p" argument on those which don't take pools
  • passed to the module init() functions
ptemp
  • sorry I lie, this pool isn't called this currently in 1.3, I renamed it this in my pthreads development. I'm referring to the use of ptrans in the parent... contrast this with the later definition of ptrans in the child.
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the end of config parsing; passed to config-time routines via cmd->temp_pool. Somewhat of a "bastard child" because it isn't available everywhere. Used for temporary scratch space which may be needed by some config routines but which is deleted at the end of config.
pchild
  • subpool of permanent_pool
  • created when a child is spawned (or a thread is created); lives until that child (thread) is destroyed
  • passed to the module child_init functions
  • destruction happens right after the child_exit functions are called... (which may explain why I think child_exit is redundant and unneeded)
ptrans
  • should be a subpool of pchild, but currently is a subpool of permanent_pool, see above
  • cleared by the child before going into the accept() loop to receive a connection
  • used as connection->pool
r->pool
  • for the main request this is a subpool of connection->pool; for subrequests it is a subpool of the parent request's pool.
  • exists until the end of the request (i.e., ap_destroy_sub_req, or in child_main after process_request has finished)
  • note that r itself is allocated from r->pool; i.e., r->pool is first created and then r is the first thing palloc()d from it

For almost everything folks do, r->pool is the pool to use. But you can see how other lifetimes, such as pchild, are useful to some modules... such as modules that need to open a database connection once per child, and wish to clean it up when the child dies.

You can also see how some bugs have manifested themself, such as setting connection->user to a value from r->pool -- in this case connection exists for the lifetime of ptrans, which is longer than r->pool (especially if r->pool is a subrequest!). So the correct thing to do is to allocate from connection->pool.

And there was another interesting bug in mod_include / mod_cgi. You'll see in those that they do this test to decide if they should use r->pool or r->main->pool. In this case the resource that they are registering for cleanup is a child process. If it were registered in r->pool, then the code would wait() for the child when the subrequest finishes. With mod_include this could be any old #include, and the delay can be up to 3 seconds... and happened quite frequently. Instead the subprocess is registered in r->main->pool which causes it to be cleaned up when the entire request is done -- i.e., after the output has been sent to the client and logging has happened.

Tracking open files, etc.

As indicated above, resource pools are also used to track other sorts of resources besides memory. The most common are open files. The routine which is typically used for this is ap_pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g.,

...
FILE *f = ap_pfopen (r->pool, r->filename, "r");

if (f == NULL) { ... } else { ... }

There is also a ap_popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared.

Unlike the case for memory, there are functions to close files allocated with ap_pfopen, and ap_popenf, namely ap_pfclose and ap_pclosef. (This is because, on many systems, the number of files which a single process can have open is quite limited). It is important to use these functions to close files allocated with ap_pfopen and ap_popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once.

(Using the close functions is not mandatory, since the file will eventually be closed regardless, but you should consider it in cases where your module is opening, or could open, a lot of files).

Other sorts of resources -- cleanup functions

More text goes here. Describe the cleanup primitives in terms of which the file stuff is implemented; also, spawn_process.

Pool cleanups live until clear_pool() is called: clear_pool(a) recursively calls destroy_pool() on all subpools of a; then calls all the cleanups for a; then releases all the memory for a. destroy_pool(a) calls clear_pool(a) and then releases the pool structure itself. i.e., clear_pool(a) doesn't delete a, it just frees up all the resources and you can start using it again immediately.

Fine control -- creating and dealing with sub-pools, with a note on sub-requests

On rare occasions, too-free use of ap_palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, allocating within the sub-pool rather than the main pool, and clearing or destroying the sub-pool, which releases the resources which were associated with it. (This really is a rare situation; the only case in which it comes up in the standard module set is in case of listing directories, and then only with very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little gain).

The primitive for creating a sub-pool is ap_make_sub_pool, which takes another pool (the parent pool) as an argument. When the main pool is cleared, the sub-pool will be destroyed. The sub-pool may also be cleared or destroyed at any time, by calling the functions ap_clear_pool and ap_destroy_pool, respectively. (The difference is that ap_clear_pool frees resources associated with the pool, while ap_destroy_pool also deallocates the pool itself. In the former case, you can allocate new resources within the pool, and clear it again, and so forth; in the latter case, it is simply gone).

One final note -- sub-requests have their own resource pools, which are sub-pools of the resource pool for the main request. The polite way to reclaim the resources associated with a sub request which you have allocated (using the ap_sub_req_... functions) is ap_destroy_sub_req, which frees the resource pool. Before calling this function, be sure to copy anything that you care about which might be allocated in the sub-request's resource pool into someplace a little less volatile (for instance, the filename in its request_rec structure).

(Again, under most circumstances, you shouldn't feel obliged to call this function; only 2K of memory or so are allocated for a typical sub request, and it will be freed anyway when the main request pool is cleared. It is only when you are allocating many, many sub-requests for a single main request that you should seriously consider the ap_destroy_... functions).

Configuration, commands and the like

One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server --- that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server's functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules.

However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to remember the commands in order to act on them later. That involves maintaining data which is private to the modules, and which can be either per-server, or per-directory. Most things are per-directory, including in particular access control and authorization information, but also information on how to determine file types from suffixes, which can be modified by AddType and ForceType directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like Aliases and Redirects which come into play before the request is tied to a particular place in the underlying file system.

Another requirement for emulating the NCSA server is being able to handle the per-directory configuration files, generally called .htaccess files, though even in the NCSA server they can contain directives which have nothing at all to do with access control. Accordingly, after URI -> filename translation, but before performing any other phase, the server walks down the directory hierarchy of the underlying filesystem, following the translated pathname, to read any .htaccess files which might be present. The information which is read in then has to be merged with the applicable information from the server's own config files (either from the <Directory> sections in access.conf, or from defaults in srm.conf, which actually behaves for most purposes almost exactly like <Directory />).

Finally, after having served a request which involved reading .htaccess files, we need to discard the storage allocated for handling them. That is solved the same way it is solved wherever else similar problems come up, by tying those structures to the per-transaction resource pool.

Per-directory configuration structures

Let's look out how all of this plays out in mod_mime.c, which defines the file typing handler which emulates the NCSA server's behavior of determining file types from suffixes. What we'll be looking at, here, is the code which implements the AddType and AddEncoding commands. These commands can appear in .htaccess files, so they must be handled in the module's private per-directory data, which in fact, consists of two separate tables for MIME types and encoding information, and is declared as follows:

typedef struct {
    table *forced_types;      /* Additional AddTyped stuff */
    table *encoding_types;    /* Added with AddEncoding... */
} mime_dir_config;

When the server is reading a configuration file, or <Directory> section, which includes one of the MIME module's commands, it needs to create a mime_dir_config structure, so those commands have something to act on. It does this by invoking the function it finds in the module's `create per-dir config slot', with two arguments: the name of the directory to which this configuration information applies (or NULL for srm.conf), and a pointer to a resource pool in which the allocation should happen.

(If we are reading a .htaccess file, that resource pool is the per-request resource pool for the request; otherwise it is a resource pool which is used for configuration data, and cleared on restarts. Either way, it is important for the structure being created to vanish when the pool is cleared, by registering a cleanup on the pool if necessary).

For the MIME module, the per-dir config creation function just ap_pallocs the structure above, and a creates a couple of tables to fill it. That looks like this:

void *create_mime_dir_config (pool *p, char *dummy)
{
mime_dir_config *new =
(mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_make_table (p, 4);
new->encoding_types = ap_make_table (p, 4);

return new;
 }

Now, suppose we've just read in a .htaccess file. We already have the per-directory configuration structure for the next directory up in the hierarchy. If the .htaccess file we just read in didn't have any AddType or AddEncoding commands, its per-directory config structure for the MIME module is still valid, and we can just use it. Otherwise, we need to merge the two structures somehow.

To do that, the server invokes the module's per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent:

void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
{
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
(mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_overlay_tables (p, subdir->forced_types,
parent_dir->forced_types);
 new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
parent_dir->encoding_types);
return new;
 }

As a note -- if there is no per-directory merge function present, the server will just use the subdirectory's configuration info, and ignore the parent's. For some modules, that works just fine (e.g., for the includes module, whose per-directory configuration information consists solely of the state of the XBITHACK), and for those modules, you can just not declare one, and leave the corresponding structure slot in the module itself NULL.

Command handling

Now that we have these structures, we need to be able to figure out how to fill them. That involves processing the actual AddType and AddEncoding commands. To find commands, the server looks in the module's command table. That table contains information on how many arguments the commands take, and in what formats, where it is permitted, and so forth. That information is sufficient to allow the server to invoke most command-handling functions with pre-parsed arguments. Without further ado, let's look at the AddType command handler, which looks like this (the AddEncoding command looks basically the same, and won't be shown here):

char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
{
if (*ext == '.') ++ext;
ap_table_set (m->forced_types, ext, ct);
return NULL;
 }

This command handler is unusually simple. As you can see, it takes four arguments, two of which are pre-parsed arguments, the third being the per-directory configuration structure for the module in question, and the fourth being a pointer to a cmd_parms structure. That structure contains a bunch of arguments which are frequently of use to some, but not all, commands, including a resource pool (from which memory can be allocated, and to which cleanups should be tied), and the (virtual) server being configured, from which the module's per-server configuration data can be obtained if required.

Another way in which this particular command handler is unusually simple is that there are no error conditions which it can encounter. If there were, it could return an error message instead of NULL; this causes an error to be printed out on the server's stderr, followed by a quick exit, if it is in the main config files; for a .htaccess file, the syntax error is logged in the server error log (along with an indication of where it came from), and the request is bounced with a server error response (HTTP error status, code 500).

The MIME module's command table has entries for these commands, which look like this:

command_rec mime_cmds[] = {
{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
"a mime type followed by a file extension" },
 { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
"an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };

The entries in these tables are:

  • The name of the command
  • The function which handles it
  • a (void *) pointer, which is passed in the cmd_parms structure to the command handler --- this is useful in case many similar commands are handled by the same function.
  • A bit mask indicating where the command may appear. There are mask bits corresponding to each AllowOverride option, and an additional mask bit, RSRC_CONF, indicating that the command may appear in the server's own config files, but not in any .htaccess file.
  • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. TAKE2 indicates two pre-parsed arguments. Other options are TAKE1, which indicates one pre-parsed argument, FLAG, which indicates that the argument should be On or Off, and is passed in as a boolean flag, RAW_ARGS, which causes the server to give the command the raw, unparsed arguments (everything but the command name itself). There is also ITERATE, which means that the handler looks the same as TAKE1, but that if multiple arguments are present, it should be called multiple times, and finally ITERATE2, which indicates that the command handler looks like a TAKE2, but if more arguments are present, then it should be called multiple times, holding the first argument constant.
  • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this NULL).

Finally, having set this all up, we have to use it. This is ultimately done in the module's handlers, specifically for its file-typing handler, which looks more or less like this; note that the per-directory configuration structure is extracted from the request_rec's per-directory configuration vector by using the ap_get_module_config function.

        int find_ct(request_rec *r)
{
int i;
char *fn = ap_pstrdup (r->pool, r->filename);
mime_dir_config *conf = (mime_dir_config *)
ap_get_module_config(r->per_dir_config, &mime_module);
char *type;

if (S_ISDIR(r->finfo.st_mode)) {
r->content_type = DIR_MAGIC_TYPE;
return OK;
}

if((i=ap_rind(fn,'.')) < 0) return DECLINED;
++i;

if ((type = ap_table_get (conf->encoding_types, &fn[i])))
{
r->content_encoding = type;

/* go back to previous extension to try to use it as a type */
fn[i-1] = '\0';
if((i=ap_rind(fn,'.')) < 0) return OK;
++i;
}

if ((type = ap_table_get (conf->forced_types, &fn[i])))
{
r->content_type = type;
}

return OK;

        }

Side notes -- per-server configuration, virtual servers, etc.

The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored).

The only substantial difference is that when a command needs to configure the per-server private module data, it needs to go to the cmd_parms data to get at it. Here's an example, from the alias module, which also indicates how a syntax error can be returned (note that the per-directory configuration argument to the command handler is declared as a dummy, since the module doesn't actually have per-directory config data):

char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
{
server_rec *s = cmd->server;
alias_server_conf *conf = (alias_server_conf *)
ap_get_module_config(s->module_config,&alias_module);
 alias_entry *new = ap_push_array (conf->redirects);

if (!ap_is_url (url)) return "Redirect to non-URL";

new->fake = f; new->real = url;
return NULL;
 }


API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

API Changes in Apache HTTP Server 2.4 since 2.2

This document describes changes to the Apache HTTPD API from version 2.2 to 2.4, that may be of interest to module/application developers and core hacks. As of the first GA release of the 2.4 branch API compatibility is preserved for the life of the 2.4 branch. (The VERSIONING description for the 2.4 release provides more information about API compatibility.)

API changes fall into two categories: APIs that are altogether new, and existing APIs that are expanded or changed. The latter are further divided into those where all changes are backwards-compatible (so existing modules can ignore them), and those that might require attention by maintainers. As with the transition from HTTPD 2.0 to 2.2, existing modules and applications will require recompiling and may call for some attention, but most should not require any substantial updating (although some may be able to take advantage of API changes to offer significant improvements).

For the purpose of this document, the API is split according to the public header files. These headers are themselves the reference documentation, and can be used to generate a browsable HTML reference with make docs.

Changed APIs

ap_expr (NEW!)

Introduces a new API to parse and evaluate boolean and algebraic expressions, including provision for a standard syntax and customised variants.

ap_listen (changed; backwards-compatible)

Introduces a new API to enable httpd child processes to serve different purposes.

ap_mpm (changed)

ap_mpm_run is replaced by a new mpm hook. Also ap_graceful_stop_signalled is lost, and ap_mpm_register_timed_callback is new.

ap_regex (changed)

In addition to the existing regexp wrapper, a new higher-level API ap_rxplus is now provided. This provides the capability to compile Perl-style expressions like s/regexp/replacement/flags and to execute them against arbitrary strings. Support for regexp backreferences is also added.

ap_slotmem (NEW!)

Introduces an API for modules to allocate and manage memory slots, most commonly for shared memory.

ap_socache (NEW!)

API to manage a shared object cache.

heartbeat (NEW!)

common structures for heartbeat modules

ap_parse_htaccess (changed)

The function signature for ap_parse_htaccess has been changed. A apr_table_t of individual directives allowed for override must now be passed (override remains).

http_config (changed)

  • Introduces per-module, per-directory loglevels, including macro wrappers.
  • New AP_DECLARE_MODULE macro to declare all modules.
  • New APLOG_USE_MODULE macro necessary for per-module loglevels in multi-file modules.
  • New API to retain data across module unload/load
  • New check_config hook
  • New ap_process_fnmatch_configs() function to process wildcards
  • Change ap_configfile_t, ap_cfg_getline(), ap_cfg_getc() to return error codes, and add ap_pcfg_strerror() for retrieving an error description.
  • Any config directive permitted in ACCESS_CONF context must now correctly handle being called from an .htaccess file via the new AllowOverrideList directive. ap_check_cmd_context() accepts a new flag NOT_IN_HTACCESS to detect this case.

http_core (changed)

  • REMOVED ap_default_type, ap_requires, all 2.2 authnz API
  • Introduces Optional Functions for logio and authnz
  • New function ap_get_server_name_for_url to support IPv6 literals.
  • New function ap_register_errorlog_handler to register error log format string handlers.
  • Arguments of error_log hook have changed. Declaration has moved to http_core.h.
  • New function ap_state_query to determine if the server is in the initial configuration preflight phase or not. This is both easier to use and more correct than the old method of creating a pool userdata entry in the process pool.
  • New function ap_get_conn_socket to get the socket descriptor for a connection. This should be used instead of accessing the core connection config directly.

httpd (changed)

  • Introduce per-directory, per-module loglevel
  • New loglevels APLOG_TRACEn
  • Introduce errorlog ids for requests and connections
  • Support for mod_request kept_body
  • Support buffering filter data for async requests
  • New CONN_STATE values
  • Function changes: ap_escape_html updated; ap_unescape_all, ap_escape_path_segment_buffer
  • Modules that load other modules later than the EXEC_ON_READ config reading stage need to call ap_reserve_module_slots() or ap_reserve_module_slots_directive() in their pre_config hook.
  • The useragent IP address per request can now be tracked independently of the client IP address of the connection, for support of deployments with load balancers.

http_log (changed)

  • Introduce per-directory, per-module loglevel
  • New loglevels APLOG_TRACEn
  • ap_log_*error become macro wrappers (backwards-compatible if APLOG_MARK macro is used, except that is no longer possible to use #ifdef inside the argument list)
  • piped logging revamped
  • module_index added to error_log hook
  • new function: ap_log_command_line

http_request (changed)

  • New auth_internal API and auth_provider API
  • New EOR bucket type
  • New function ap_process_async_request
  • New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI
  • New access_checker_ex hook to apply additional access control and/or bypass authentication.
  • New functions ap_hook_check_access_ex, ap_hook_check_access, ap_hook_check_authn, ap_hook_check_authz which accept AP_AUTH_INTERNAL_PER_* flags
  • DEPRECATED direct use of ap_hook_access_checker, access_checker_ex, ap_hook_check_user_id, ap_hook_auth_checker

When possible, registering all access control hooks (including authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF is recommended. If all modules' access control hooks are registered with this flag, then whenever the server handles an internal sub-request that matches the same set of access control configuration directives as the initial request (which is the common case), it can avoid invoking the access control hooks another time.

If your module requires the old behavior and must perform access control checks on every sub-request with a different URI from the initial request, even if that URI matches the same set of access control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.

mod_auth (NEW!)

Introduces the new provider framework for authn and authz

mod_cache (changed)

Introduces a commit_entity() function to the cache provider interface, allowing atomic writes to cache. Add a cache_status() hook to report the cache decision. All private structures and functions were removed.

mod_core (NEW!)

This introduces low-level APIs to send arbitrary headers, and exposes functions to handle HTTP OPTIONS and TRACE.

mod_cache_disk (changed)

Changes the disk format of the disk cache to support atomic cache updates without locking. The device/inode pair of the body file is embedded in the header file, allowing confirmation that the header and body belong to one another.

mod_disk_cache (renamed)

The mod_disk_cache module has been renamed to mod_cache_disk in order to be consistent with the naming of other modules within the server.

mod_request (NEW!)

The API for mod_request, to make input data available to multiple application/handler modules where required, and to parse HTML form data.

mpm_common (changed)

  • REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)
  • NEW API to drop privileges (delegates this platform-dependent function to modules)
  • NEW Hooks: mpm_query, timed_callback, and get_name
  • CHANGED interfaces: monitor hook, ap_reclaim_child_processes, ap_relieve_child_processes

scoreboard (changed)

ap_get_scoreboard_worker is made non-backwards-compatible as an alternative version is introduced. Additional proxy_balancer support. Child status stuff revamped.

util_cookies (NEW!)

Introduces a new API for managing HTTP Cookies.

util_ldap (changed)

no description available

util_mutex (NEW!)

A wrapper for APR proc and global mutexes in httpd, providing common configuration for the underlying mechanism and location of lock files.

util_script (changed)

NEW: ap_args_to_table

util_time (changed)

NEW: ap_recent_ctime_ex

Specific information on upgrading modules from 2.2

Logging

In order to take advantage of per-module loglevel configuration, any source file that calls the ap_log_* functions should declare which module it belongs to. If the module's module_struct is called foo_module, the following code can be used to remain backward compatible with HTTPD 2.0 and 2.2:

#include <http_log.h>

#ifdef APLOG_USE_MODULE
APLOG_USE_MODULE(foo);
#endif

Note: This is absolutely required for C++-language modules. It can be skipped for C-language modules, though that breaks module-specific log level support for files without it.

The number of parameters of the ap_log_* functions and the definition of APLOG_MARK has changed. Normally, the change is completely transparent. However, changes are required if a module uses APLOG_MARK as a parameter to its own functions or if a module calls ap_log_* without passing APLOG_MARK. A module which uses wrappers around ap_log_* typically uses both of these constructs.

The easiest way to change code which passes APLOG_MARK to its own functions is to define and use a different macro that expands to the parameters required by those functions, as APLOG_MARK should only be used when calling ap_log_* directly. In this way, the code will remain compatible with HTTPD 2.0 and 2.2.

Code which calls ap_log_* without passing APLOG_MARK will necessarily differ between 2.4 and earlier releases, as 2.4 requires a new third argument, APLOG_MODULE_INDEX.

/* code for httpd 2.0/2.2 */
ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

/* code for httpd 2.4 */
ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

ap_log_*error are now implemented as macros. This means that it is no longer possible to use #ifdef inside the argument list of ap_log_*error, as this would cause undefined behavor according to C99.

A server_rec pointer must be passed to ap_log_error() when called after startup. This was always appropriate, but there are even more limitations with a NULL server_rec in 2.4 than in previous releases. Beginning with 2.3.12, the global variable ap_server_conf can always be used as the server_rec parameter, as it will be NULL only when it is valid to pass NULL to ap_log_error(). ap_server_conf should be used only when a more appropriate server_rec is not available.

Consider the following changes to take advantage of the new APLOG_TRACE1..8 log levels:

  • Check current use of APLOG_DEBUG and consider if one of the APLOG_TRACEn levels is more appropriate.
  • If your module currently has a mechanism for configuring the amount of debug logging which is performed, consider eliminating that mechanism and relying on the use of different APLOG_TRACEn levels. If expensive trace processing needs to be bypassed depending on the configured log level, use the APLOGtracen and APLOGrtracen macros to first check if tracing is enabled.

Modules sometimes add process id and/or thread id to their log messages. These ids are now logged by default, so it may not be necessary for the module to log them explicitly. (Users may remove them from the error log format, but they can be instructed to add it back if necessary for problem diagnosis.)

If your module uses these existing APIs...

ap_default_type()
This is no longer available; Content-Type must be configured explicitly or added by the application.
ap_get_server_name()
If the returned server name is used in a URL, use ap_get_server_name_for_url() instead. This new function handles the odd case where the server name is an IPv6 literal address.
ap_get_server_version()
For logging purposes, where detailed information is appropriate, use ap_get_server_description(). When generating output, where the amount of information should be configurable by ServerTokens, use ap_get_server_banner().
ap_graceful_stop_signalled()
Replace with a call to ap_mpm_query(AP_MPMQ_MPM_STATE) and checking for state AP_MPMQ_STOPPING.
ap_max_daemons_limit, ap_my_generation, and ap_threads_per_child
Use ap_mpm_query() query codes AP_MPMQ_MAX_DAEMON_USED, AP_MPMQ_GENERATION, and AP_MPMQ_MAX_THREADS, respectively.
ap_mpm_query()
Ensure that it is not used until after the register-hooks hook has completed. Otherwise, an MPM built as a DSO would not have had a chance to enable support for this function.
ap_requires()
The core server now provides better infrastructure for handling Require configuration. Register an auth provider function for each supported entity using ap_register_auth_provider(). The function will be called as necessary during Require processing. (Consult bundled modules for detailed examples.)
ap_server_conf->process->pool userdata
Optional:
  • If your module uses this to determine which pass of the startup hooks is being run, use ap_state_query(AP_SQ_MAIN_STATE).
  • If your module uses this to maintain data across the unloading and reloading of your module, use ap_retained_data_create() and ap_retained_data_get().
apr_global_mutex_create(), apr_proc_mutex_create()
Optional: See ap_mutex_register(), ap_global_mutex_create(), and ap_proc_mutex_create(); these allow your mutexes to be configurable with the Mutex directive; you can also remove any configuration mechanisms in your module for such mutexes
CORE_PRIVATE
This is now unnecessary and ignored.
dav_new_error() and dav_new_error_tag()
Previously, these assumed that errno contained information describing the failure. Now, an apr_status_t parameter must be provided. Pass 0/APR_SUCCESS if there is no such error information, or a valid apr_status_t value otherwise.
mpm_default.h, DEFAULT_LOCKFILE, DEFAULT_THREAD_LIMIT, DEFAULT_PIDLOG, etc.
The header file and most of the default configuration values set in it are no longer visible to modules. (Most can still be overridden at build time.) DEFAULT_PIDLOG and DEFAULT_REL_RUNTIMEDIR are now universally available via ap_config.h.
unixd_config
This has been renamed to ap_unixd_config.
unixd_setup_child()
This has been renamed to ap_unixd_setup_child(), but most callers should call the added ap_run_drop_privileges() hook.
conn_rec->remote_ip and conn_rec->remote_addr
These fields have been renamed in order to distinguish between the client IP address of the connection and the useragent IP address of the request (potentially overridden by a load balancer or proxy). References to either of these fields must be updated with one of the following options, as appropriate for the module:
  • When you require the IP address of the user agent, which might be connected directly to the server, or might optionally be separated from the server by a transparent load balancer or proxy, use request_rec->useragent_ip and request_rec->useragent_addr.
  • When you require the IP address of the client that is connected directly to the server, which might be the useragent or might be the load balancer or proxy itself, use conn_rec->client_ip and conn_rec->client_addr.

If your module interfaces with this feature...

suEXEC
Optional: If your module logs an error when ap_unixd_config.suexec_enabled is 0, also log the value of the new field suexec_disabled_reason, which contains an explanation of why it is not available.
Extended status data in the scoreboard
In previous releases, ExtendedStatus had to be set to On, which in turn required that mod_status was loaded. In 2.4, just set ap_extended_status to 1 in a pre-config hook and the extended status data will be available.

Does your module...

Parse query args
Consider if ap_args_to_table() would be helpful.
Parse form data...
Use ap_parse_form_data().
Check for request header fields Content-Length and Transfer-Encoding to see if a body was specified
Use ap_request_has_body().
Implement cleanups which clear pointer variables
Use ap_pool_cleanup_set_null().
Create run-time files such as shared memory files, pid files, etc.
Use ap_runtime_dir_relative() so that the global configuration for the location of such files, either by the DEFAULT_REL_RUNTIMEDIR compile setting or the DefaultRuntimeDir directive, will be respected. Apache httpd 2.4.2 and above.


Developing modules for the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer

Developing modules for the Apache HTTP Server 2.4

This document explains how you can develop modules for the Apache HTTP Server 2.4

See also

  • Request Processing in Apache 2.4
  • Apache 2.x Hook Functions

Introduction

What we will be discussing in this document

This document will discuss how you can create modules for the Apache HTTP Server 2.4, by exploring an example module called mod_example. In the first part of this document, the purpose of this module will be to calculate and print out various digest values for existing files on your web server, whenever we access the URL http://hostname/filename.sum. For instance, if we want to know the MD5 digest value of the file located at http://www.example.com/index.html, we would visit http://www.example.com/index.html.sum.

In the second part of this document, which deals with configuration directive and context awareness, we will be looking at a module that simply writes out its own configuration to the client.

Prerequisites

First and foremost, you are expected to have a basic knowledge of how the C programming language works. In most cases, we will try to be as pedagogical as possible and link to documents describing the functions used in the examples, but there are also many cases where it is necessary to either just assume that "it works" or do some digging yourself into what the hows and whys of various function calls.

Lastly, you will need to have a basic understanding of how modules are loaded and configured in the Apache HTTP Server, as well as how to get the headers for Apache if you do not have them already, as these are needed for compiling new modules.

Compiling your module

To compile the source code we are building in this document, we will be using APXS. Assuming your source file is called mod_example.c, compiling, installing and activating the module is as simple as:

apxs -i -a -c mod_example.c

Defining a module

Module name tags
Every module starts with the same declaration, or name tag if you will, that defines a module as a separate entity within Apache:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf, /* Per-directory configuration handler */
    merge_dir_conf,  /* Merge handler for per-directory configurations */
    create_svr_conf, /* Per-server configuration handler */
    merge_svr_conf,  /* Merge handler for per-server configurations */
    directives,      /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

This bit of code lets the server know that we have now registered a new module in the system, and that its name is example_module. The name of the module is used primarily for two things:

  • Letting the server know how to load the module using the LoadModule
  • Setting up a namespace for the module to use in configurations

For now, we're only concerned with the first purpose of the module name, which comes into play when we need to load the module:

LoadModule example_module modules/mod_example.so

In essence, this tells the server to open up mod_example.so and look for a module called example_module.

Within this name tag of ours is also a bunch of references to how we would like to handle things: Which directives do we respond to in a configuration file or .htaccess, how do we operate within specific contexts, and what handlers are we interested in registering with the Apache HTTP service. We'll return to all these elements later in this document.

Getting started: Hooking into the server

An introduction to hooks

When handling requests in Apache HTTP Server 2.4, the first thing you will need to do is create a hook into the request handling process. A hook is essentially a message telling the server that you are willing to either serve or at least take a glance at certain requests given by clients. All handlers, whether it's mod_rewrite, mod_authn_*, mod_proxy and so on, are hooked into specific parts of the request process. As you are probably aware, modules serve different purposes; Some are authentication/authorization handlers, others are file or script handlers while some third modules rewrite URIs or proxies content. Furthermore, in the end, it is up to the user of the server how and when each module will come into place. Thus, the server itself does not presume to know which module is responsible for handling a specific request, and will ask each module whether they have an interest in a given request or not. It is then up to each module to either gently decline serving a request, accept serving it or flat out deny the request from being served, as authentication/authorization modules do:
Hook handling in httpd
To make it a bit easier for handlers such as our mod_example to know whether the client is requesting content we should handle or not, the server has directives for hinting to modules whether their assistance is needed or not. Two of these are AddHandler and SetHandler. Let's take a look at an example using AddHandler. In our example case, we want every request ending with .sum to be served by mod_example, so we'll add a configuration directive that tells the server to do just that:

AddHandler example-handler .sum

What this tells the server is the following: Whenever we receive a request for a URI ending in .sum, we are to let all modules know that we are looking for whoever goes by the name of "example-handler" . Thus, when a request is being served that ends in .sum, the server will let all modules know, that this request should be served by "example-handler ". As you will see later, when we start building mod_example, we will check for this handler tag relayed by AddHandler and reply to the server based on the value of this tag.

Hooking into httpd

To begin with, we only want to create a simple handler, that replies to the client browser when a specific URL is requested, so we won't bother setting up configuration handlers and directives just yet. Our initial module definition will look like this:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    register_hooks   /* Our hook registering function */
};

This lets the server know that we are not interested in anything fancy, we just want to hook onto the requests and possibly handle some of them.

The reference in our example declaration, register_hooks is the name of a function we will create to manage how we hook onto the request process. In this example module, the function has just one purpose; To create a simple hook that gets called after all the rewrites, access control etc has been handled. Thus, we will let the server know, that we want to hook into its process as one of the last modules:

static void register_hooks(apr_pool_t *pool)
{
    /* Create a hook in the request handler, so we get called when a request arrives */
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

The example_handler reference is the function that will handle the request. We will discuss how to create a handler in the next chapter.

Other useful hooks

Hooking into the request handling phase is but one of many hooks that you can create. Some other ways of hooking are:

  • ap_hook_child_init: Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked)
  • ap_hook_pre_config: Place a hook that executes before any configuration data has been read (very early hook)
  • ap_hook_post_config: Place a hook that executes after configuration has been parsed, but before the server has forked
  • ap_hook_translate_name: Place a hook that executes when a URI needs to be translated into a filename on the server (think mod_rewrite)
  • ap_hook_quick_handler: Similar to ap_hook_handler, except it is run before any other request hooks (translation, auth, fixups etc)
  • ap_hook_log_transaction: Place a hook that executes when the server is about to add a log entry of the current request

Building a handler

A handler is essentially a function that receives a callback when a request to the server is made. It is passed a record of the current request (how it was made, which headers and requests were passed along, who's giving the request and so on), and is put in charge of either telling the server that it's not interested in the request or handle the request with the tools provided.

A simple "Hello, world!" handler

Let's start off by making a very simple request handler that does the following:

  1. Check that this is a request that should be served by "example-handler"
  2. Set the content type of our output to text/html
  3. Write "Hello, world!" back to the client browser
  4. Let the server know that we took care of this request and everything went fine

In C code, our example handler will now look like this:

static int example_handler(request_rec *r)
{
    /* First off, we need to check if this is a call for the "example-handler" handler.
     * If it is, we accept it and do our things, if not, we simply return DECLINED,
     * and the server will try somewhere else.
     */
    if (!r->handler || strcmp(r->handler, "example-handler")) return (DECLINED);

    /* Now that we are handling this request, we'll write out "Hello, world!" to the client.
     * To do so, we must first set the appropriate content type, followed by our output.
     */
    ap_set_content_type(r, "text/html");
    ap_rprintf(r, "Hello, world!");

    /* Lastly, we must tell the server that we took care of this request and everything went fine.
     * We do so by simply returning the value OK to the server.
     */
    return OK;
}

Now, we put all we have learned together and end up with a program that looks like mod_example_1.c . The functions used in this example will be explained later in the section "Some useful functions you should know".

The request_rec structure

The most essential part of any request is the request record . In a call to a handler function, this is represented by the request_rec* structure passed along with every call that is made. This struct, typically just referred to as r in modules, contains all the information you need for your module to fully process any HTTP request and respond accordingly.

Some key elements of the request_rec structure are:

  • r->handler (char*): Contains the name of the handler the server is currently asking to do the handling of this request
  • r->method (char*): Contains the HTTP method being used, f.x. GET or POST
  • r->filename (char*): Contains the translated filename the client is requesting
  • r->args (char*): Contains the query string of the request, if any
  • r->headers_in (apr_table_t*): Contains all the headers sent by the client
  • r->connection (conn_rec*): A record containing information about the current connection
  • r->user (char*): If the URI requires authentication, this is set to the username provided
  • r->useragent_ip (char*): The IP address of the client connecting to us
  • r->pool (apr_pool_t*): The memory pool of this request. We'll discuss this in the "Memory management" chapter.

A complete list of all the values contained within the request_rec structure can be found in the httpd.h header file or at http://ci.apache.org/projects/httpd/trunk/doxygen/structrequest__rec.html.

Let's try out some of these variables in another example handler:

static int example_handler(request_rec *r)
{
    /* Set the appropriate content type */
    ap_set_content_type(r, "text/html");

    /* Print out the IP address of the client connecting to us: */
    ap_rprintf(r, "<h2>Hello, %s!</h2>", r->useragent_ip);

    /* If we were reached through a GET or a POST request, be happy, else sad. */
    if ( !strcmp(r->method, "POST") || !strcmp(r->method, "GET") ) {
        ap_rputs("You used a GET or a POST method, that makes us happy!<br/>", r);
    }
    else {
        ap_rputs("You did not use POST or GET, that makes us sad :(<br/>", r);
    }

    /* Lastly, if there was a query string, let's print that too! */
    if (r->args) {
        ap_rprintf(r, "Your query string was: %s", r->args);
    }
    return OK;
}

Return values

Apache relies on return values from handlers to signify whether a request was handled or not, and if so, whether the request went well or not. If a module is not interested in handling a specific request, it should always return the value DECLINED. If it is handling a request, it should either return the generic value OK, or a specific HTTP status code, for example:

static int example_handler(request_rec *r)
{
    /* Return 404: Not found */
    return HTTP_NOT_FOUND;
}

Returning OK or a HTTP status code does not necessarily mean that the request will end. The server may still have other handlers that are interested in this request, for instance the logging modules which, upon a successful request, will write down a summary of what was requested and how it went. To do a full stop and prevent any further processing after your module is done, you can return the value DONE to let the server know that it should cease all activity on this request and carry on with the next, without informing other handlers.
General response codes:

  • DECLINED: We are not handling this request
  • OK: We handled this request and it went well
  • DONE: We handled this request and the server should just close this thread without further processing

HTTP specific return codes (excerpt):

  • HTTP_OK (200): Request was okay
  • HTTP_MOVED_PERMANENTLY (301): The resource has moved to a new URL
  • HTTP_UNAUTHORIZED (401): Client is not authorized to visit this page
  • HTTP_FORBIDDEN (403): Permission denied
  • HTTP_NOT_FOUND (404): File not found
  • HTTP_INTERNAL_SERVER_ERROR (500): Internal server error (self explanatory)

Some useful functions you should know

  • ap_rputs(const char *string, request_rec *r):
    Sends a string of text to the client. This is a shorthand version of ap_rwrite.
    ap_rputs("Hello, world!", r);
  • ap_rprintf:
    This function works just like printf, except it sends the result to the client.
    ap_rprintf(r, "Hello, %s!", r->useragent_ip);
  • ap_set_content_type(request_rec *r, const char *type):
    Sets the content type of the output you are sending.
    ap_set_content_type(r, "text/plain"); /* force a raw text output */

Memory management

Managing your resources in Apache HTTP Server 2.4 is quite easy, thanks to the memory pool system. In essence, each server, connection and request have their own memory pool that gets cleaned up when its scope ends, e.g. when a request is done or when a server process shuts down. All your module needs to do is latch onto this memory pool, and you won't have to worry about having to clean up after yourself - pretty neat, huh?

In our module, we will primarily be allocating memory for each request, so it's appropriate to use the r->pool reference when creating new objects. A few of the functions for allocating memory within a pool are:

  • void* apr_palloc( apr_pool_t *p, apr_size_t size): Allocates size number of bytes in the pool for you
  • void* apr_pcalloc( apr_pool_t *p, apr_size_t size): Allocates size number of bytes in the pool for you and sets all bytes to 0
  • char* apr_pstrdup( apr_pool_t *p, const char *s): Creates a duplicate of the string s. This is useful for copying constant values so you can edit them
  • char* apr_psprintf( apr_pool_t *p, const char *fmt, ...): Similar to sprintf, except the server supplies you with an appropriately allocated target variable

Let's put these functions into an example handler:

static int example_handler(request_rec *r)
{
    const char *original = "You can't edit this!";
    char *copy;
    int *integers;

    /* Allocate space for 10 integer values and set them all to zero. */
    integers = apr_pcalloc(r->pool, sizeof(int)*10);

    /* Create a copy of the 'original' variable that we can edit. */
    copy = apr_pstrdup(r->pool, original);
    return OK;
}

This is all well and good for our module, which won't need any pre-initialized variables or structures. However, if we wanted to initialize something early on, before the requests come rolling in, we could simply add a call to a function in our register_hooks function to sort it out:

static void register_hooks(apr_pool_t *pool)
{
    /* Call a function that initializes some stuff */
    example_init_function(pool);
    /* Create a hook in the request handler, so we get called when a request arrives */
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

In this pre-request initialization function we would not be using the same pool as we did when allocating resources for request-based functions. Instead, we would use the pool given to us by the server for allocating memory on a per-process based level.

Parsing request data

In our example module, we would like to add a feature, that checks which type of digest, MD5 or SHA1 the client would like to see. This could be solved by adding a query string to the request. A query string is typically comprised of several keys and values put together in a string, for instance valueA=yes&valueB=no&valueC=maybe. It is up to the module itself to parse these and get the data it requires. In our example, we'll be looking for a key called digest, and if set to md5, we'll produce an MD5 digest, otherwise we'll produce a SHA1 digest.

Since the introduction of Apache HTTP Server 2.4, parsing request data from GET and POST requests have never been easier. All we require to parse both GET and POST data is four simple lines:

apr_table_t *GET;
apr_array_header_t*POST;

ap_args_to_table(r, &GET);

ap_parse_form_data(r, NULL, &POST, -1, 8192);

In our specific example module, we're looking for the digest value from the query string, which now resides inside a table called GET. To extract this value, we need only perform a simple operation:

/* Get the "digest" key from the query string, if any. */
const char *digestType = apr_table_get(GET, "digest");

/* If no key was returned, we will set a default value instead. */
if (!digestType) digestType = "sha1";

The structures used for the POST and GET data are not exactly the same, so if we were to fetch a value from POST data instead of the query string, we would have to resort to a few more lines, as outlined in this example in the last chapter of this document.

Making an advanced handler

Now that we have learned how to parse form data and manage our resources, we can move on to creating an advanced version of our module, that spits out the MD5 or SHA1 digest of files:

static int example_handler(request_rec *r)
{
    int rc, exists;
    apr_finfo_t finfo;
    apr_file_t *file;
    char *filename;
    char buffer[256];
    apr_size_t readBytes;
    int n;
    apr_table_t *GET;
    apr_array_header_t *POST;
    const char *digestType;

    /* Check that the "example-handler" handler is being called. */
    if (!r->handler || strcmp(r->handler, "example-handler")) return (DECLINED);

    /* Figure out which file is being requested by removing the .sum from it */
    filename = apr_pstrdup(r->pool, r->filename);
    filename[strlen(filename)-4] = 0; /* Cut off the last 4 characters. */

    /* Figure out if the file we request a sum on exists and isn't a directory */
    rc = apr_stat(&finfo, filename, APR_FINFO_MIN, r->pool);
    if (rc == APR_SUCCESS) {
        exists =
        (
            (finfo.filetype != APR_NOFILE)
        &&  !(finfo.filetype & APR_DIR)
        );
        if (!exists) return HTTP_NOT_FOUND; /* Return a 404 if not found. */
    }
    /* If apr_stat failed, we're probably not allowed to check this file. */
    else return HTTP_FORBIDDEN;

    /* Parse the GET and, optionally, the POST data sent to us */

    ap_args_to_table(r, &GET);
    ap_parse_form_data(r, NULL, &POST, -1, 8192);

    /* Set the appropriate content type */
    ap_set_content_type(r, "text/html");

    /* Print a title and some general information */
    ap_rprintf(r, "<h2>Information on %s:</h2>", filename);
    ap_rprintf(r, "<b>Size:</b> %u bytes<br/>", finfo.size);

    /* Get the digest type the client wants to see */
    digestType = apr_table_get(GET, "digest");
    if (!digestType) digestType = "MD5";

    rc = apr_file_open(&file, filename, APR_READ, APR_OS_DEFAULT, r->pool);
    if (rc == APR_SUCCESS) {

        /* Are we trying to calculate the MD5 or the SHA1 digest? */
        if (!strcasecmp(digestType, "md5")) {
            /* Calculate the MD5 sum of the file */
            union {
                char      chr[16];
                uint32_t  num[4];
            } digest;
            apr_md5_ctx_t md5;
            apr_md5_init(&md5);
            readBytes = 256;
            while ( apr_file_read(file, buffer, &readBytes) == APR_SUCCESS ) {
                apr_md5_update(&md5, buffer, readBytes);
            }
            apr_md5_final(digest.chr, &md5);

            /* Print out the MD5 digest */
            ap_rputs("<b>MD5: </b><code>", r);
            for (n = 0; n < APR_MD5_DIGESTSIZE/4; n++) {
                ap_rprintf(r, "%08x", digest.num[n]);
            }
            ap_rputs("</code>", r);
            /* Print a link to the SHA1 version */
            ap_rputs("<br/><a href='?digest=sha1'>View the SHA1 hash instead</a>", r);
        }
        else {
            /* Calculate the SHA1 sum of the file */
            union {
                char      chr[20];
                uint32_t  num[5];
            } digest;
            apr_sha1_ctx_t sha1;
            apr_sha1_init(&sha1);
            readBytes = 256;
            while ( apr_file_read(file, buffer, &readBytes) == APR_SUCCESS ) {
                apr_sha1_update(&sha1, buffer, readBytes);
            }
            apr_sha1_final(digest.chr, &sha1);

            /* Print out the SHA1 digest */
            ap_rputs("<b>SHA1: </b><code>", r);
            for (n = 0; n < APR_SHA1_DIGESTSIZE/4; n++) {
                ap_rprintf(r, "%08x", digest.num[n]);
            }
            ap_rputs("</code>", r);

            /* Print a link to the MD5 version */
            ap_rputs("<br/><a href='?digest=md5'>View the MD5 hash instead</a>", r);
        }
        apr_file_close(file);

    }
    /* Let the server know that we responded to this request. */
    return OK;
}

This version in its entirety can be found here: mod_example_2.c.

Adding configuration options

In this next segment of this document, we will turn our eyes away from the digest module and create a new example module, whose only function is to write out its own configuration. The purpose of this is to examine how the server works with configuration, and what happens when you start writing advanced configurations for your modules.

An introduction to configuration directives

If you are reading this, then you probably already know what a configuration directive is. Simply put, a directive is a way of telling an individual module (or a set of modules) how to behave, such as these directives control how mod_rewrite works:

RewriteEngine On
RewriteCond "%{REQUEST_URI}" "^/foo/bar"
RewriteRule "^/foo/bar/(.*)$" "/foobar?page=$1"

Each of these configuration directives are handled by a separate function, that parses the parameters given and sets up a configuration accordingly.

Making an example configuration

To begin with, we'll create a basic configuration in C-space:

typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

Now, let's put this into perspective by creating a very small module that just prints out a hard-coded configuration. You'll notice that we use the register_hooks function for initializing the configuration values to their defaults:

typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

static example_config config;

static int example_handler(request_rec *r)
{
    if (!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config.enabled);
    ap_rprintf(r, "Path: %s\n", config.path);
    ap_rprintf(r, "TypeOfAction: %x\n", config.typeOfAction);
    return OK;
}

static void register_hooks(apr_pool_t *pool)
{
    config.enabled = 1;
    config.path = "/foo/bar";
    config.typeOfAction = 0x00;
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

/* Define our module as an entity and assign a function for registering hooks  */

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,            /* Per-directory configuration handler */
    NULL,            /* Merge handler for per-directory configurations */
    NULL,            /* Per-server configuration handler */
    NULL,            /* Merge handler for per-server configurations */
    NULL,            /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

So far so good. To access our new handler, we could add the following to our configuration:

<Location "/example">
    SetHandler example-handler
</Location>

When we visit, we'll see our current configuration being spit out by our module.

Registering directives with the server

What if we want to change our configuration, not by hard-coding new values into the module, but by using either the httpd.conf file or possibly a .htaccess file? It's time to let the server know that we want this to be possible. To do so, we must first change our name tag to include a reference to the configuration directives we want to register with the server:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,               /* Per-directory configuration handler */
    NULL,               /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    example_directives, /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

This will tell the server that we are now accepting directives from the configuration files, and that the structure called example_directives holds information on what our directives are and how they work. Since we have three different variables in our module configuration, we will add a structure with three directives and a NULL at the end:

static const command_rec        example_directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, RSRC_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, RSRC_CONF, "Special action value!"),
    { NULL }
};

Directives structure
As you can see, each directive needs at least 5 parameters set:

  1. AP_INIT_TAKE1: This is a macro that tells the server that this directive takes one and only one argument. If we required two arguments, we could use the macro AP_INIT_TAKE2 and so on (refer to httpd_conf.h for more macros).
  2. exampleEnabled: This is the name of our directive. More precisely, it is what the user must put in his/her configuration in order to invoke a configuration change in our module.
  3. example_set_enabled: This is a reference to a C function that parses the directive and sets the configuration accordingly. We will discuss how to make this in the following paragraph.
  4. RSRC_CONF: This tells the server where the directive is permitted. We'll go into details on this value in the later chapters, but for now, RSRC_CONF means that the server will only accept these directives in a server context.
  5. "Enable or disable....": This is simply a brief description of what the directive does.

(The "missing" parameter in our definition, which is usually set to NULL, is an optional function that can be run after the initial function to parse the arguments have been run. This is usually omitted, as the function for verifying arguments might as well be used to set them.)

The directive handler function

Now that we have told the server to expect some directives for our module, it's time to make a few functions for handling these. What the server reads in the configuration file(s) is text, and so naturally, what it passes along to our directive handler is one or more strings, that we ourselves need to recognize and act upon. You'll notice, that since we set our exampleAction directive to accept two arguments, its C function also has an additional parameter defined:

/* Handler for the "exampleEnabled" directive */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    if(!strcasecmp(arg, "on")) config.enabled = 1;
    else config.enabled = 0;
    return NULL;
}

/* Handler for the "examplePath" directive */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    config.path = arg;
    return NULL;
}

/* Handler for the "exampleAction" directive */
/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */
/* and we store it in a bit-wise manner. */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    if(!strcasecmp(arg1, "file")) config.typeOfAction = 0x01;
    else config.typeOfAction = 0x02;

    if(!strcasecmp(arg2, "deny")) config.typeOfAction += 0x10;
    else config.typeOfAction += 0x20;
    return NULL;
}

Putting it all together

Now that we have our directives set up, and handlers configured for them, we can assemble our module into one big file:

/* mod_example_config_simple.c: */
#include <stdio.h>
#include "apr_hash.h"
#include "ap_config.h"
#include "ap_provider.h"
#include "httpd.h"
#include "http_core.h"
#include "http_config.h"
#include "http_log.h"
#include "http_protocol.h"
#include "http_request.h"

/*
 ==============================================================================
 Our configuration prototype and declaration:
 ==============================================================================
 */
typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

static example_config config;

/*
 ==============================================================================
 Our directive handlers:
 ==============================================================================
 */
/* Handler for the "exampleEnabled" directive */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    if(!strcasecmp(arg, "on")) config.enabled = 1;
    else config.enabled = 0;
    return NULL;
}

/* Handler for the "examplePath" directive */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    config.path = arg;
    return NULL;
}

/* Handler for the "exampleAction" directive */
/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */
/* and we store it in a bit-wise manner. */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    if(!strcasecmp(arg1, "file")) config.typeOfAction = 0x01;
    else config.typeOfAction = 0x02;

    if(!strcasecmp(arg2, "deny")) config.typeOfAction += 0x10;
    else config.typeOfAction += 0x20;
    return NULL;
}

/*
 ==============================================================================
 The directive structure for our name tag:
 ==============================================================================
 */
static const command_rec        example_directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, RSRC_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, RSRC_CONF, "Special action value!"),
    { NULL }
};
/*
 ==============================================================================
 Our module handler:
 ==============================================================================
 */
static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config.enabled);
    ap_rprintf(r, "Path: %s\n", config.path);
    ap_rprintf(r, "TypeOfAction: %x\n", config.typeOfAction);
    return OK;
}

/*
 ==============================================================================
 The hook registration function (also initializes the default config values):
 ==============================================================================
 */
static void register_hooks(apr_pool_t *pool)
{
    config.enabled = 1;
    config.path = "/foo/bar";
    config.typeOfAction = 3;
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}
/*
 ==============================================================================
 Our module name tag:
 ==============================================================================
 */
module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,               /* Per-directory configuration handler */
    NULL,               /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    example_directives, /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

In our httpd.conf file, we can now change the hard-coded configuration by adding a few lines:

ExampleEnabled On
ExamplePath "/usr/bin/foo"
ExampleAction file allow

And thus we apply the configuration, visit /example on our web site, and we see the configuration has adapted to what we wrote in our configuration file.

Context aware configurations

Introduction to context aware configurations

In Apache HTTP Server 2.4, different URLs, virtual hosts, directories etc can have very different meanings to the user of the server, and thus different contexts within which modules must operate. For example, let's assume you have this configuration set up for mod_rewrite:

<Directory "/var/www">
    RewriteCond "%{HTTP_HOST}" "^example.com$"
    RewriteRule "(.*)" "http://www.example.com/$1"
</Directory>
<Directory "/var/www/sub">
    RewriteRule "^foobar$" "index.php?foobar=true"
</Directory>

In this example, you will have set up two different contexts for mod_rewrite:

  1. Inside /var/www, all requests for http://example.com must go to http://www.example.com
  2. Inside /var/www/sub, all requests for foobar must go to index.php?foobar=true

If mod_rewrite (or the entire server for that matter) wasn't context aware, then these rewrite rules would just apply to every and any request made, regardless of where and how they were made, but since the module can pull the context specific configuration straight from the server, it does not need to know itself, which of the directives are valid in this context, since the server takes care of this.

So how does a module get the specific configuration for the server, directory or location in question? It does so by making one simple call:

example_config *config = (example_config*) ap_get_module_config(r->per_dir_config, &example_module);

That's it! Of course, a whole lot goes on behind the scenes, which we will discuss in this chapter, starting with how the server came to know what our configuration looks like, and how it came to be set up as it is in the specific context.

Our basic configuration setup

In this chapter, we will be working with a slightly modified version of our previous context structure. We will set a context variable that we can use to track which context configuration is being used by the server in various places:

typedef struct {
    char        context[256];
    char        path[256];
    int         typeOfAction;
    int         enabled;
} example_config;

Our handler for requests will also be modified, yet still very simple:

static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    example_config *config = (example_config*) ap_get_module_config(r->per_dir_config, &example_module);
    ap_set_content_type(r, "text/plain");
    ap_rprintf("Enabled: %u\n", config->enabled);
    ap_rprintf("Path: %s\n", config->path);
    ap_rprintf("TypeOfAction: %x\n", config->typeOfAction);
    ap_rprintf("Context: %s\n", config->context);
    return OK;
}

Choosing a context

Before we can start making our module context aware, we must first define, which contexts we will accept. As we saw in the previous chapter, defining a directive required five elements be set:

AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),

The RSRC_CONF definition told the server that we would only allow this directive in a global server context, but since we are now trying out a context aware version of our module, we should set this to something more lenient, namely the value ACCESS_CONF, which lets us use the directive inside <Directory> and <Location> blocks. For more control over the placement of your directives, you can combine the following restrictions together to form a specific rule:

  • RSRC_CONF: Allow in .conf files (not .htaccess) outside <Directory> or <Location>
  • ACCESS_CONF: Allow in .conf files (not .htaccess) inside <Directory> or <Location>
  • OR_OPTIONS: Allow in .conf files and .htaccess when AllowOverride Options is set
  • OR_FILEINFO: Allow in .conf files and .htaccess when AllowOverride FileInfo is set
  • OR_AUTHCFG: Allow in .conf files and .htaccess when AllowOverride AuthConfig is set
  • OR_INDEXES: Allow in .conf files and .htaccess when AllowOverride Indexes is set
  • OR_ALL: Allow anywhere in .conf files and .htaccess

Using the server to allocate configuration slots

A much smarter way to manage your configurations is by letting the server help you create them. To do so, we must first start off by changing our name tag to let the server know, that it should assist us in creating and managing our configurations. Since we have chosen the per-directory (or per-location) context for our module configurations, we'll add a per-directory creator and merger function reference in our tag:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf, /* Per-directory configuration handler */
    merge_dir_conf,  /* Merge handler for per-directory configurations */
    NULL,            /* Per-server configuration handler */
    NULL,            /* Merge handler for per-server configurations */
    directives,      /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

Creating new context configurations

Now that we have told the server to help us create and manage configurations, our first step is to make a function for creating new, blank configurations. We do so by creating the function we just referenced in our name tag as the Per-directory configuration handler:

void *create_dir_conf(apr_pool_t *pool, char *context) {
    context = context ? context : "(undefined context)";
    example_config *cfg = apr_pcalloc(pool, sizeof(example_config));
    if(cfg) {
        /* Set some default values */
        strcpy(cfg->context, context);
        cfg->enabled = 0;
        cfg->path = "/foo/bar";
        cfg->typeOfAction = 0x11;
    }
    return cfg;
}

Merging configurations

Our next step in creating a context aware configuration is merging configurations. This part of the process particularly applies to scenarios where you have a parent configuration and a child, such as the following:

<Directory "/var/www">
    ExampleEnabled On
    ExamplePath "/foo/bar"
    ExampleAction file allow
</Directory>
<Directory "/var/www/subdir">
    ExampleAction file deny
</Directory>

In this example, it is natural to assume that the directory /var/www/subdir should inherit the values set for the /var/www directory, as we did not specify an ExampleEnabled nor an ExamplePath for this directory. The server does not presume to know if this is true, but cleverly does the following:

  1. Creates a new configuration for /var/www
  2. Sets the configuration values according to the directives given for /var/www
  3. Creates a new configuration for /var/www/subdir
  4. Sets the configuration values according to the directives given for /var/www/subdir
  5. Proposes a merge of the two configurations into a new configuration for /var/www/subdir

This proposal is handled by the merge_dir_conf function we referenced in our name tag. The purpose of this function is to assess the two configurations and decide how they are to be merged:

void *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD) {
    example_config *base = (example_config *) BASE ; /* This is what was set in the parent context */
    example_config *add = (example_config *) ADD ;   /* This is what is set in the new context */
    example_config *conf = (example_config *) create_dir_conf(pool, "Merged configuration"); /* This will be the merged configuration */

    /* Merge configurations */
    conf->enabled = ( add->enabled == 0 ) ? base->enabled : add->enabled ;
    conf->typeOfAction = add->typeOfAction ? add->typeOfAction : base->typeOfAction;
    strcpy(conf->path, strlen(add->path) ? add->path : base->path);

    return conf ;
}

Trying out our new context aware configurations

Now, let's try putting it all together to create a new module that is context aware. First off, we'll create a configuration that lets us test how the module works:

<Location "/a">
    SetHandler example-handler
    ExampleEnabled on
    ExamplePath "/foo/bar"
    ExampleAction file allow
</Location>

<Location "/a/b">
    ExampleAction file deny
    ExampleEnabled off
</Location>

<Location "/a/b/c">
    ExampleAction db deny
    ExamplePath "/foo/bar/baz"
    ExampleEnabled on
</Location>

Then we'll assemble our module code. Note, that since we are now using our name tag as reference when fetching configurations in our handler, I have added some prototypes to keep the compiler happy:

/*$6
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 * mod_example_config.c
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 */

#include <stdio.h>
#include "apr_hash.h"
#include "ap_config.h"
#include "ap_provider.h"
#include "httpd.h"
#include "http_core.h"
#include "http_config.h"
#include "http_log.h"
#include "http_protocol.h"
#include "http_request.h"

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

typedef struct
{
    char    context[256];
    char    path[256];
    int     typeOfAction;
    int     enabled;
} example_config;

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Prototypes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

static int    example_handler(request_rec *r);
const char    *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg);
const char    *example_set_path(cmd_parms *cmd, void *cfg, const char *arg);
const char    *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2);
void          *create_dir_conf(apr_pool_t *pool, char *context);
void          *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD);
static void   register_hooks(apr_pool_t *pool);

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration directives
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

static const command_rec    directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, ACCESS_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, ACCESS_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, ACCESS_CONF, "Special action value!"),
    { NULL }
};

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Our name tag
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

module AP_MODULE_DECLARE_DATA    example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf,    /* Per-directory configuration handler */
    merge_dir_conf,     /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    directives,         /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

/*
 =======================================================================================================================
    Hook registration function
 =======================================================================================================================
 */
static void register_hooks(apr_pool_t *pool)
{
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

/*
 =======================================================================================================================
    Our example web service handler
 =======================================================================================================================
 */
static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);

    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *config = (example_config *) ap_get_module_config(r->per_dir_config, &example_module);
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config->enabled);
    ap_rprintf(r, "Path: %s\n", config->path);
    ap_rprintf(r, "TypeOfAction: %x\n", config->typeOfAction);
    ap_rprintf(r, "Context: %s\n", config->context);
    return OK;
}

/*
 =======================================================================================================================
    Handler for the "exampleEnabled" directive
 =======================================================================================================================
 */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        if(!strcasecmp(arg, "on"))
            conf->enabled = 1;
        else
            conf->enabled = 0;
    }

    return NULL;
}

/*
 =======================================================================================================================
    Handler for the "examplePath" directive
 =======================================================================================================================
 */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        strcpy(conf->path, arg);
    }

    return NULL;
}

/*
 =======================================================================================================================
    Handler for the "exampleAction" directive ;
    Let's pretend this one takes one argument (file or db), and a second (deny or allow), ;
    and we store it in a bit-wise manner.
 =======================================================================================================================
 */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        {
            if(!strcasecmp(arg1, "file"))
                conf->typeOfAction = 0x01;
            else
                conf->typeOfAction = 0x02;
            if(!strcasecmp(arg2, "deny"))
                conf->typeOfAction += 0x10;
            else
                conf->typeOfAction += 0x20;
        }
    }

    return NULL;
}

/*
 =======================================================================================================================
    Function for creating new configurations for per-directory contexts
 =======================================================================================================================
 */
void *create_dir_conf(apr_pool_t *pool, char *context)
{
    context = context ? context : "Newly created configuration";

    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *cfg = apr_pcalloc(pool, sizeof(example_config));
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(cfg)
    {
        {
            /* Set some default values */
            strcpy(cfg->context, context);
            cfg->enabled = 0;
            memset(cfg->path, 0, 256);
            cfg->typeOfAction = 0x00;
        }
    }

    return cfg;
}

/*
 =======================================================================================================================
    Merging function for configurations
 =======================================================================================================================
 */
void *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *base = (example_config *) BASE;
    example_config    *add = (example_config *) ADD;
    example_config    *conf = (example_config *) create_dir_conf(pool, "Merged configuration");
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    conf->enabled = (add->enabled == 0) ? base->enabled : add->enabled;
    conf->typeOfAction = add->typeOfAction ? add->typeOfAction : base->typeOfAction;
    strcpy(conf->path, strlen(add->path) ? add->path : base->path);
    return conf;
}

Summing up

We have now looked at how to create simple modules for Apache HTTP Server 2.4 and configuring them. What you do next is entirely up to you, but it is my hope that something valuable has come out of reading this documentation. If you have questions on how to further develop modules, you are welcome to join our mailing lists or check out the rest of our documentation for further tips.

Some useful snippets of code

Retrieve variables from POST form data

typedef struct {
    const char *key;
    const char *value;
} keyValuePair;

keyValuePair *readPost(request_rec *r) {
    apr_array_header_t *pairs = NULL;
    apr_off_t len;
    apr_size_t size;
    int res;
    int i = 0;
    char *buffer;
    keyValuePair *kvp;

    res = ap_parse_form_data(r, NULL, &pairs, -1, HUGE_STRING_LEN);
    if (res != OK || !pairs) return NULL; /* Return NULL if we failed or if there are is no POST data */
    kvp = apr_pcalloc(r->pool, sizeof(keyValuePair) * (pairs->nelts + 1));
    while (pairs && !apr_is_empty_array(pairs)) {
        ap_form_pair_t *pair = (ap_form_pair_t *) apr_array_pop(pairs);
        apr_brigade_length(pair->value, 1, &len);
        size = (apr_size_t) len;
        buffer = apr_palloc(r->pool, size + 1);
        apr_brigade_flatten(pair->value, buffer, &size);
        buffer[len] = 0;
        kvp[i].key = apr_pstrdup(r->pool, pair->name);
        kvp[i].value = buffer;
        i++;
    }
    return kvp;
}

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~~~~~~~*/
    keyValuePair *formData;
    /*~~~~~~~~~~~~~~~~~~~~~~*/

    formData = readPost(r);
    if (formData) {
        int i;
        for (i = 0; &formData[i]; i++) {
            if (formData[i].key && formData[i].value) {
                ap_rprintf(r, "%s = %s\n", formData[i].key, formData[i].value);
            } else if (formData[i].key) {
                ap_rprintf(r, "%s\n", formData[i].key);
            } else if (formData[i].value) {
                ap_rprintf(r, "= %s\n", formData[i].value);
            } else {
                break;
            }
        }
    }
    return OK;
}

Printing out every HTTP header received

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    const apr_array_header_t    *fields;
    int                         i;
    apr_table_entry_t           *e = 0;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    fields = apr_table_elts(r->headers_in);
    e = (apr_table_entry_t *) fields->elts;
    for(i = 0; i < fields->nelts; i++) {
        ap_rprintf(r, "%s: %s\n", e[i].key, e[i].val);
    }
    return OK;
}

Reading the request body into memory

static int util_read(request_rec *r, const char **rbuf, apr_off_t *size)
{
    /*~~~~~~~~*/
    int rc = OK;
    /*~~~~~~~~*/

    if((rc = ap_setup_client_block(r, REQUEST_CHUNKED_ERROR))) {
        return(rc);
    }

    if(ap_should_client_block(r)) {

        /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
        char         argsbuffer[HUGE_STRING_LEN];
        apr_off_t    rsize, len_read, rpos = 0;
        apr_off_t length = r->remaining;
        /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

        *rbuf = (const char *) apr_pcalloc(r->pool, (apr_size_t) (length + 1));
        *size = length;
        while((len_read = ap_get_client_block(r, argsbuffer, sizeof(argsbuffer))) > 0) {
            if((rpos + len_read) > length) {
                rsize = length - rpos;
            }
            else {
                rsize = len_read;
            }

            memcpy((char *) *rbuf + rpos, argsbuffer, (size_t) rsize);
            rpos += rsize;
        }
    }
    return(rc);
}

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~*/
    apr_off_t   size;
    const char  *buffer;
    /*~~~~~~~~~~~~~~~~*/

    if(util_read(r, &buffer, &size) == OK) {
        ap_rprintf(r, "We read a request body that was %" APR_OFF_T_FMT " bytes long", size);
    }
    return OK;
}


Documenting code in Apache 2.4 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Documenting code in Apache 2.4

Apache 2.4 uses Doxygen to document the APIs and global variables in the code. This will explain the basics of how to document using Doxygen.

Brief Description

To start a documentation block, use /**
To end a documentation block, use */

In the middle of the block, there are multiple tags we can use:

Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function

The deffunc is not always necessary. DoxyGen does not have a full parser in it, so any prototype that use a macro in the return type declaration is too complex for scandoc. Those functions require a deffunc. An example (using &gt; rather than >):

/**
 * return the final element of the pathname
 * @param pathname The path to get the final element of
 * @return the final element of the path
 * @tip Examples:
 * <pre>
 * "/foo/bar/gum" -&gt; "gum"
 * "/foo/bar/gum/" -&gt; ""
 * "gum" -&gt; "gum"
 * "wi\\n32\\stuff" -&gt; "stuff"
 * </pre>
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)
 */

At the top of the header file, always include:

/**
 * @package Name of library header
 */

Doxygen uses a new HTML file for each package. The HTML files are named {Name_of_library_header}.html, so try to be concise with your names.

For a further discussion of the possibilities please refer to the Doxygen site.


Hook Functions in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Hook Functions in the Apache HTTP Server 2.x

Warning

This document is still in development and may be partially out of date.

In general, a hook function is one that the Apache HTTP Server will call at some point during the processing of a request. Modules can provide functions that are called, and specify when they get called in comparison to other modules.

Core Hooks

The httpd's core modules offer a predefinined list of hooks used during the standard request processing phase. Creating a new hook will expose a function that implements it (see sections below) but it is essential to undestand that you will not extend the httpd's core hooks. Their presence and order in the request processing is in fact a consequence of how they are called in server/request.c (check this section for an overview). The core hooks are listed in the doxygen documentation.

Reading guide for developing modules and request processing before proceeding is highly recomended.

Creating a hook function

In order to create a new hook, four things need to be done:

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given the return type of the hook function, the name of the hook, and the arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))

This should go in a header which modules will include if they want to use the hook.

Create the hook structure

Each source file that exports a hook has a private structure which is used to record the module functions that use the hook. This is declared as follows:

APR_HOOK_STRUCT(
  APR_HOOK_LINK(do_something)
  ...
)

Implement the hook caller

The source file that exports the hook has to implement a function that will call the hook. There are currently three possible ways to do this. In all cases, the calling function is called ap_run_hookname().

Void hooks

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

void ap_run_do_something(request_rec *r, int n)
{
    ...
    do_something(r, n);
}

Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook caller. Note that DECLINED is the traditional hook return value meaning "I didn't do anything", but it can be whatever suits you.

Alternatively, all hooks can be run until an error occurs. This boils down to permitting two return values, one of which means "I did something, and it was OK" and the other meaning "I did nothing". The first function that returns a value other than one of those two stops the loop, and its return is the return value. Declare these like so:

AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)

Again, OK and DECLINED are the traditional values. You can use what you want.

Call the hook callers

At appropriate moments in the code, call the hook caller, like so:

int n, ret;
request_rec *r;

ret=ap_run_do_something(r, n);

Hooking the hook

A module that wants a hook to be called needs to do two things.

Implement the hook function

Include the appropriate header, and define a static function of the correct type:

static int my_something_doer(request_rec *r, int n)

{
    ...
    return OK;
}

Add a hook registering function

During initialisation, the server will call each modules hook registering function, which is included in the module structure:

static void my_register_hooks()
{
    ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
}

mode MODULE_VAR_EXPORT my_module =
{
    ...
    my_register_hooks       /* register hooks */
};

Controlling hook calling order

In the example above, we didn't use the three arguments in the hook registration function that control calling order of all the functions registered within the hook. There are two mechanisms for doing this. The first, rather crude, method, allows us to specify roughly where the hook is run relative to other modules. The final argument control this. There are three possible values: APR_HOOK_FIRST, APR_HOOK_MIDDLE and APR_HOOK_LAST.

All modules using any particular value may be run in any order relative to each other, but, of course, all modules using APR_HOOK_FIRST will be run before APR_HOOK_MIDDLE which are before APR_HOOK_LAST. Modules that don't care when they are run should use APR_HOOK_MIDDLE. These values are spaced out, so that positions like APR_HOOK_FIRST-2 are possible to hook slightly earlier than other functions.

Note that there are two more values, APR_HOOK_REALLY_FIRST and APR_HOOK_REALLY_LAST. These should only be used by the hook exporter.

The other method allows finer control. When a module knows that it must be run before (or after) some other modules, it can specify them by name. The second (third) argument is a NULL-terminated array of strings consisting of the names of modules that must be run before (after) the current module. For example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

static void register_hooks()
{
    static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };

    ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
}

Note that the sort used to achieve this is stable, so ordering set by APR_HOOK_ORDER is preserved, as far as is possible.


Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Converting Modules from Apache 1.3 to Apache 2.0

This is a first attempt at writing the lessons I learned when trying to convert the mod_mmap_static module to Apache 2.0. It's by no means definitive and probably won't even be correct in some ways, but it's a start.

The easier changes ...

Cleanup Routines

These now need to be of type apr_status_t and return a value of that type. Normally the return value will be APR_SUCCESS unless there is some need to signal an error in the cleanup. Be aware that even though you signal an error not all code yet checks and acts upon the error.

Initialisation Routines

These should now be renamed to better signify where they sit in the overall process. So the name gets a small change from mmap_init to mmap_post_config. The arguments passed have undergone a radical change and now look like

  • apr_pool_t *p
  • apr_pool_t *plog
  • apr_pool_t *ptemp
  • server_rec *s

Data Types

A lot of the data types have been moved into the APR. This means that some have had a name change, such as the one shown above. The following is a brief list of some of the changes that you are likely to have to make.

  • pool becomes apr_pool_t
  • table becomes apr_table_t

The messier changes...

Register Hooks

The new architecture uses a series of hooks to provide for calling your functions. These you'll need to add to your module by way of a new function, static void register_hooks(void). The function is really reasonably straightforward once you understand what needs to be done. Each function that needs calling at some stage in the processing of a request needs to be registered, handlers do not. There are a number of phases where functions can be added, and for each you can specify with a high degree of control the relative order that the function will be called in.

This is the code that was added to mod_mmap_static:

static void register_hooks(void)
{
    static const char * const aszPre[]={ "http_core.c",NULL };
    ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
    ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
};

This registers 2 functions that need to be called, one in the post_config stage (virtually every module will need this one) and one for the translate_name phase. note that while there are different function names the format of each is identical. So what is the format?

ap_hook_phase_name(function_name, predecessors, successors, position);

There are 3 hook positions defined...

  • HOOK_FIRST
  • HOOK_MIDDLE
  • HOOK_LAST

To define the position you use the position and then modify it with the predecessors and successors. Each of the modifiers can be a list of functions that should be called, either before the function is run (predecessors) or after the function has run (successors).

In the mod_mmap_static case I didn't care about the post_config stage, but the mmap_static_xlat must be called after the core module had done its name translation, hence the use of the aszPre to define a modifier to the position HOOK_LAST.

Module Definition

There are now a lot fewer stages to worry about when creating your module definition. The old definition looked like

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD_MODULE_STUFF,
    /* initializer */
    /* dir config creater */
    /* dir merger --- default is to override */
    /* server config */
    /* merge server config */
    /* command handlers */
    /* handlers */
    /* filename translation */
    /* check_user_id */
    /* check auth */
    /* check access */
    /* type_checker */
    /* fixups */
    /* logger */
    /* header parser */
    /* child_init */
    /* child_exit */
    /* post read-request */
};

The new structure is a great deal simpler...

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD20_MODULE_STUFF,
    /* create per-directory config structures */
    /* merge per-directory config structures  */
    /* create per-server config structures    */
    /* merge per-server config structures     */
    /* command handlers */
    /* handlers */
    /* register hooks */
};

Some of these read directly across, some don't. I'll try to summarise what should be done below.

The stages that read directly across :

/* dir config creater */
/* create per-directory config structures */
/* server config */
/* create per-server config structures */
/* dir merger */
/* merge per-directory config structures */
/* merge server config */
/* merge per-server config structures */
/* command table */
/* command apr_table_t */
/* handlers */
/* handlers */

The remainder of the old functions should be registered as hooks. There are the following hook stages defined so far...

ap_hook_pre_config
do any setup required prior to processing configuration directives
ap_hook_check_config
review configuration directive interdependencies
ap_hook_test_config
executes only with -t option
ap_hook_open_logs
open any specified logs
ap_hook_post_config
this is where the old _init routines get registered
ap_hook_http_method
retrieve the http method from a request. (legacy)
ap_hook_auth_checker
check if the resource requires authorization
ap_hook_access_checker
check for module-specific restrictions
ap_hook_check_user_id
check the user-id and password
ap_hook_default_port
retrieve the default port for the server
ap_hook_pre_connection
do any setup required just before processing, but after accepting
ap_hook_process_connection
run the correct protocol
ap_hook_child_init
call as soon as the child is started
ap_hook_create_request
??
ap_hook_fixups
last chance to modify things before generating content
ap_hook_handler
generate the content
ap_hook_header_parser
lets modules look at the headers, not used by most modules, because they use post_read_request for this
ap_hook_insert_filter
to insert filters into the filter chain
ap_hook_log_transaction
log information about the request
ap_hook_optional_fn_retrieve
retrieve any functions registered as optional
ap_hook_post_read_request
called after reading the request, before any other phase
ap_hook_quick_handler
called before any request processing, used by cache modules.
ap_hook_translate_name
translate the URI into a filename
ap_hook_type_checker
determine and/or set the doc type


Request Processing in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Request Processing in the Apache HTTP Server 2.x

Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in 2.0 and above affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.

The first major change is to the subrequest and redirect mechanisms. There were a number of different code paths in the Apache HTTP Server 1.3 to attempt to optimize subrequest or redirect behavior. As patches were introduced to 2.0, these optimizations (and the server behavior) were quickly broken due to this duplication of code. All duplicate code has been folded back into ap_process_request_internal() to prevent the code from falling out of sync again.

This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of 1.3) without introducing fragile or insecure code.

The Request Processing Cycle

All requests pass through ap_process_request_internal() in server/request.c, including subrequests and redirects. If a module doesn't pass generated requests through this code, the author is cautioned that the module may be broken by future changes to request processing.

To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core hooks which are irrelevant (and costly in terms of CPU.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only once, at the beginning of internal request processing.

This step is bypassed if the proxyreq flag is set, or the parsed_uri.path element is unset. The module has no further control of this one-time unescape operation, either failing to unescape or multiply unescaping the URL leads to security repercussions.

Strips Parent and This Elements from the URI

All /../ and /./ elements are removed by ap_getparents(). This helps to ensure the path is (nearly) absolute before the request processing continues.

This step cannot be bypassed.

Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that <Location> sections are consistently enforced for all requests. If the request is an internal redirect or a sub-request, it may borrow some or all of the processing from the previous or parent request's ap_location_walk, so this step is generally very efficient after processing the main request.

translate_name

Modules can determine the file name, or alter the given URI in this step. For example, mod_vhost_alias will translate the URI's path into the configured virtual host, mod_alias will translate the path to an alias path, and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't translate name" error is logged automatically.

Hook: map_to_storage

After the file or correct URI was determined, the appropriate per-dir configurations are merged together. For example, mod_proxy compares and merges the appropriate <Proxy> sections. If the URI is nothing more than a local (non-proxy) TRACE request, the core handles the request and returns DONE. If no module answers this hook with OK or DONE, the core will run the request filename against the <Directory> and <Files> sections. If the request 'filename' isn't an absolute, legal filename, a note is set for later termination.

URI Location Walk

Every request is hardened by a second ap_location_walk() call. This reassures that a translated request is still subjected to the configured <Location> sections. The request again borrows some or all of the processing from its previous location_walk above, so this step is almost always very efficient unless the translated URI mapped to a substantially different path or Virtual Host.

Hook: header_parser

The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.

The Security Phase

Needs Documentation. Code is:

if ((access_status = ap_run_access_checker(r)) != 0) {
    return decl_die(access_status, "check access", r);
}

if ((access_status = ap_run_check_user_id(r)) != 0) {
    return decl_die(access_status, "check user", r);
}

if ((access_status = ap_run_auth_checker(r)) != 0) {
    return decl_die(access_status, "check authorization", r);
}

The Preparation Phase

Hook: type_checker

The modules have an opportunity to test the URI or filename against the target resource, and set mime information for the request. Both mod_mime and mod_mime_magic use this phase to compare the file name or contents against the administrator's configuration and set the content type, language, character set and request handler. Some modules may set up their filters or other request handling parameters at this time.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't find types" error is logged automatically.

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.

The Handler Phase

This phase is not part of the processing in ap_process_request_internal(). Many modules prepare one or more subrequests prior to creating any content at all. After the core, or a module calls ap_process_request_internal() it then calls ap_invoke_handler() to generate the request.

Hook: insert_filter

Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.

Hook: handler

The module finally has a chance to serve the request in its handler hook. Note that not every prepared request is sent to the handler hook. Many modules, such as mod_autoindex, will create subrequests for a given URI, and then never serve the subrequest, but simply lists it for the user. Remember not to put required teardown from the hooks above into this module, but register pool cleanups against the request pool to free resources as required.


How filters work in Apache 2.0 - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

How filters work in Apache 2.0

Warning

This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.

Filter Types

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. (AP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)
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. (AP_FTYPE_PROTOCOL, AP_FTYPE_TRANSCODE)
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. (AP_FTYPE_RESOURCE, AP_FTYPE_CONTENT_SET)

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:

  • r->output_filters (corresponds to RESOURCE)
  • r->proto_output_filters (corresponds to PROTOCOL)
  • r->connection->output_filters (corresponds to CONNECTION)

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 --> ...

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 --> ...
                                    /
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.

Explanations

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.


Guide to writing output filters - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Guide to writing output filters

There are a number of common pitfalls encountered when writing output filters; this page aims to document best practice for authors of new or existing filters.

This document is applicable to both version 2.0 and version 2.2 of the Apache HTTP Server; it specifically targets RESOURCE-level or CONTENT_SET-level filters though some advice is generic to all types of filter.

Filters and bucket brigades

Each time a filter is invoked, it is passed a bucket brigade, containing a sequence of buckets which represent both data content and metadata. Every bucket has a bucket type; a number of bucket types are defined and used by the httpd core modules (and the apr-util library which provides the bucket brigade interface), but modules are free to define their own types.

Output filters must be prepared to process buckets of non-standard types; with a few exceptions, a filter need not care about the types of buckets being filtered.

A filter can tell whether a bucket represents either data or metadata using the APR_BUCKET_IS_METADATA macro. Generally, all metadata buckets should be passed down the filter chain by an output filter. Filters may transform, delete, and insert data buckets as appropriate.

There are two metadata bucket types which all filters must pay attention to: the EOS bucket type, and the FLUSH bucket type. An EOS bucket indicates that the end of the response has been reached and no further buckets need be processed. A FLUSH bucket indicates that the filter should flush any buffered buckets (if applicable) down the filter chain immediately.

FLUSH buckets are sent when the content generator (or an upstream filter) knows that there may be a delay before more content can be sent. By passing FLUSH buckets down the filter chain immediately, filters ensure that the client is not kept waiting for pending data longer than necessary.

Filters can create FLUSH buckets and pass these down the filter chain if desired. Generating FLUSH buckets unnecessarily, or too frequently, can harm network utilisation since it may force large numbers of small packets to be sent, rather than a small number of larger packets. The section on Non-blocking bucket reads covers a case where filters are encouraged to generate FLUSH buckets.

Example bucket brigade

HEAP FLUSH FILE EOS

This shows a bucket brigade which may be passed to a filter; it contains two metadata buckets (FLUSH and EOS), and two data buckets (HEAP and FILE).

Filter invocation

For any given request, an output filter might be invoked only once and be given a single brigade representing the entire response. It is also possible that the number of times a filter is invoked for a single response is proportional to the size of the content being filtered, with the filter being passed a brigade containing a single bucket each time. Filters must operate correctly in either case.

An output filter which allocates long-lived memory every time it is invoked may consume memory proportional to response size. Output filters which need to allocate memory should do so once per response; see Maintaining state below.

An output filter can distinguish the final invocation for a given response by the presence of an EOS bucket in the brigade. Any buckets in the brigade after an EOS should be ignored.

An output filter should never pass an empty brigade down the filter chain. To be defensive, filters should be prepared to accept an empty brigade, and should return success without passing this brigade on down the filter chain. The handling of an empty brigade should have no side effects (such as changing any state private to the filter).

How to handle an empty brigade

    apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)

    {
        if (APR_BRIGADE_EMPTY(bb)) {
            return APR_SUCCESS;
        }
        ....

Brigade structure

A bucket brigade is a doubly-linked list of buckets. The list is terminated (at both ends) by a sentinel which can be distinguished from a normal bucket by comparing it with the pointer returned by APR_BRIGADE_SENTINEL. The list sentinel is in fact not a valid bucket structure; any attempt to call normal bucket functions (such as apr_bucket_read) on the sentinel will have undefined behaviour (i.e. will crash the process).

There are a variety of functions and macros for traversing and manipulating bucket brigades; see the apr_buckets.h header for complete coverage. Commonly used macros include:

APR_BRIGADE_FIRST(bb)
returns the first bucket in brigade bb
APR_BRIGADE_LAST(bb)
returns the last bucket in brigade bb
APR_BUCKET_NEXT(e)
gives the next bucket after bucket e
APR_BUCKET_PREV(e)
gives the bucket before bucket e

The apr_bucket_brigade structure itself is allocated out of a pool, so if a filter creates a new brigade, it must ensure that memory use is correctly bounded. A filter which allocates a new brigade out of the request pool (r->pool) on every invocation, for example, will fall foul of the warning above concerning memory use. Such a filter should instead create a brigade on the first invocation per request, and store that brigade in its state structure.

It is generally never advisable to use apr_brigade_destroy to "destroy" a brigade unless you know for certain that the brigade will never be used again, even then, it should be used rarely. The memory used by the brigade structure will not be released by calling this function (since it comes from a pool), but the associated pool cleanup is unregistered. Using apr_brigade_destroy can in fact cause memory leaks; if a "destroyed" brigade contains buckets when its containing pool is destroyed, those buckets will not be immediately destroyed.

In general, filters should use apr_brigade_cleanup in preference to apr_brigade_destroy.

Processing buckets

When dealing with non-metadata buckets, it is important to understand that the "apr_bucket *" object is an abstract representation of data:

  1. The amount of data represented by the bucket may or may not have a determinate length; for a bucket which represents data of indeterminate length, the ->length field is set to the value (apr_size_t)-1. For example, buckets of the PIPE bucket type have an indeterminate length; they represent the output from a pipe.
  2. The data represented by a bucket may or may not be mapped into memory. The FILE bucket type, for example, represents data stored in a file on disk.

Filters read the data from a bucket using the apr_bucket_read function. When this function is invoked, the bucket may morph into a different bucket type, and may also insert a new bucket into the bucket brigade. This must happen for buckets which represent data not mapped into memory.

To give an example; consider a bucket brigade containing a single FILE bucket representing an entire file, 24 kilobytes in size:

FILE(0K-24K)

When this bucket is read, it will read a block of data from the file, morph into a HEAP bucket to represent that data, and return the data to the caller. It also inserts a new FILE bucket representing the remainder of the file; after the apr_bucket_read call, the brigade looks like:

HEAP(8K) FILE(8K-24K)

Filtering brigades

The basic function of any output filter will be to iterate through the passed-in brigade and transform (or simply examine) the content in some manner. The implementation of the iteration loop is critical to producing a well-behaved output filter.

Taking an example which loops through the entire brigade as follows:

Bad output filter -- do not imitate!

apr_bucket *e = APR_BRIGADE_FIRST(bb);
const char *data;
apr_size_t length;

while (e != APR_BRIGADE_SENTINEL(bb)) {
    apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
    e = APR_BUCKET_NEXT(e);
}

return ap_pass_brigade(bb);

The above implementation would consume memory proportional to content size. If passed a FILE bucket, for example, the entire file contents would be read into memory as each apr_bucket_read call morphed a FILE bucket into a HEAP bucket.

In contrast, the implementation below will consume a fixed amount of memory to filter any brigade; a temporary brigade is needed and must be allocated only once per response, see the Maintaining state section.

Better output filter

apr_bucket *e;
const char *data;
apr_size_t length;

while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
   rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
   if (rv) ...;
   /* Remove bucket e from bb. */
   APR_BUCKET_REMOVE(e);
   /* Insert it into  temporary brigade. */
   APR_BRIGADE_INSERT_HEAD(tmpbb, e);
   /* Pass brigade downstream. */
   rv = ap_pass_brigade(f->next, tmpbb);
   if (rv) ...;
   apr_brigade_cleanup(tmpbb);
}

Maintaining state

A filter which needs to maintain state over multiple invocations per response can use the ->ctx field of its ap_filter_t structure. It is typical to store a temporary brigade in such a structure, to avoid having to allocate a new brigade per invocation as described in the Brigade structure section.

Example code to maintain filter state

struct dummy_state {
   apr_bucket_brigade *tmpbb;
   int filter_state;
   ...
};

apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
{

    struct dummy_state *state;

    state = f->ctx;
    if (state == NULL) {

       /* First invocation for this response: initialise state structure.
        */
       f->ctx = state = apr_palloc(f->r->pool, sizeof *state);

       state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);
       state->filter_state = ...;

    }
    ...

Buffering buckets

If a filter decides to store buckets beyond the duration of a single filter function invocation (for example storing them in its ->ctx state structure), those buckets must be set aside. This is necessary because some bucket types provide buckets which represent temporary resources (such as stack memory) which will fall out of scope as soon as the filter chain completes processing the brigade.

To setaside a bucket, the apr_bucket_setaside function can be called. Not all bucket types can be setaside, but if successful, the bucket will have morphed to ensure it has a lifetime at least as long as the pool given as an argument to the apr_bucket_setaside function.

Alternatively, the ap_save_brigade function can be used, which will move all the buckets into a separate brigade containing buckets with a lifetime as long as the given pool argument. This function must be used with care, taking into account the following points:

  1. On return, ap_save_brigade guarantees that all the buckets in the returned brigade will represent data mapped into memory. If given an input brigade containing, for example, a PIPE bucket, ap_save_brigade will consume an arbitrary amount of memory to store the entire output of the pipe.
  2. When ap_save_brigade reads from buckets which cannot be setaside, it will always perform blocking reads, removing the opportunity to use Non-blocking bucket reads.
  3. If ap_save_brigade is used without passing a non-NULL "saveto" (destination) brigade parameter, the function will create a new brigade, which may cause memory use to be proportional to content size as described in the Brigade structure section.
Filters must ensure that any buffered data is processed and passed down the filter chain during the last invocation for a given response (a brigade containing an EOS bucket). Otherwise such data will be lost.

Non-blocking bucket reads

The apr_bucket_read function takes an apr_read_type_e argument which determines whether a blocking or non-blocking read will be performed from the data source. A good filter will first attempt to read from every data bucket using a non-blocking read; if that fails with APR_EAGAIN, then send a FLUSH bucket down the filter chain, and retry using a blocking read.

This mode of operation ensures that any filters further down the filter chain will flush any buffered buckets if a slow content source is being used.

A CGI script is an example of a slow content source which is implemented as a bucket type. mod_cgi will send PIPE buckets which represent the output from a CGI script; reading from such a bucket will block when waiting for the CGI script to produce more output.

Example code using non-blocking bucket reads

apr_bucket *e;
apr_read_type_e mode = APR_NONBLOCK_READ;

while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
    apr_status_t rv;

    rv = apr_bucket_read(e, &data, &length, mode);
    if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {

        /* Pass down a brigade containing a flush bucket: */
        APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
        rv = ap_pass_brigade(f->next, tmpbb);
        apr_brigade_cleanup(tmpbb);
        if (rv != APR_SUCCESS) return rv;

        /* Retry, using a blocking read. */
        mode = APR_BLOCK_READ;
        continue;
    } else if (rv != APR_SUCCESS) {
        /* handle errors */
    }

    /* Next time, try a non-blocking read first. */
    mode = APR_NONBLOCK_READ;
    ...
}

Ten rules for output filters

In summary, here is a set of rules for all output filters to follow:

  1. Output filters should not pass empty brigades down the filter chain, but should be tolerant of being passed empty brigades.
  2. Output filters must pass all metadata buckets down the filter chain; FLUSH buckets should be respected by passing any pending or buffered buckets down the filter chain.
  3. Output filters should ignore any buckets following an EOS bucket.
  4. Output filters must process a fixed amount of data at a time, to ensure that memory consumption is not proportional to the size of the content being filtered.
  5. Output filters should be agnostic with respect to bucket types, and must be able to process buckets of unfamiliar type.
  6. After calling ap_pass_brigade to pass a brigade down the filter chain, output filters should call apr_brigade_cleanup to ensure the brigade is empty before reusing that brigade structure; output filters should never use apr_brigade_destroy to "destroy" brigades.
  7. Output filters must setaside any buckets which are preserved beyond the duration of the filter function.
  8. Output filters must not ignore the return value of ap_pass_brigade, and must return appropriate errors back up the filter chain.
  9. Output filters must only create a fixed number of bucket brigades for each response, rather than one per invocation.
  10. Output filters should first attempt non-blocking reads from each data bucket, and send a FLUSH bucket down the filter chain if the read blocks, before retrying with a blocking read.


Apache HTTP Server 2.x Thread Safety Issues - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Apache HTTP Server 2.x Thread Safety Issues

When using any of the threaded mpms in the Apache HTTP Server 2.x it is important that every function called from Apache be thread safe. When linking in 3rd party extensions it can be difficult to determine whether the resulting server will be thread safe. Casual testing generally won't tell you this either as thread safety problems can lead to subtle race conditions that may only show up in certain conditions under heavy load.

Global and static variables

When writing your module or when trying to determine if a module or 3rd party library is thread safe there are some common things to keep in mind.

First, you need to recognize that in a threaded model each individual thread has its own program counter, stack and registers. Local variables live on the stack, so those are fine. You need to watch out for any static or global variables. This doesn't mean that you are absolutely not allowed to use static or global variables. There are times when you actually want something to affect all threads, but generally you need to avoid using them if you want your code to be thread safe.

In the case where you have a global variable that needs to be global and accessed by all threads, be very careful when you update it. If, for example, it is an incrementing counter, you need to atomically increment it to avoid race conditions with other threads. You do this using a mutex (mutual exclusion). Lock the mutex, read the current value, increment it and write it back and then unlock the mutex. Any other thread that wants to modify the value has to first check the mutex and block until it is cleared.

If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_* functions.

errno

This is a common global variable that holds the error number of the last error that occurred. If one thread calls a low-level function that sets errno and then another thread checks it, we are bleeding error numbers from one thread into another. To solve this, make sure your module or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread variable and should hopefully be transparent to the code. It does this by doing something like this:

#define errno (*(__errno_location()))

which means that accessing errno will call __errno_location() which is provided by the libc. Setting _REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes changes the common getc/putc macros into safer function calls. Check your libc documentation for specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are _POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.

Common standard troublesome functions

Not only do things have to be thread safe, but they also have to be reentrant. strtok() is an obvious one. You call it the first time with your delimiter which it then remembers and on each subsequent call it returns the next token. Obviously if multiple threads are calling it you will have a problem. Most systems have a reentrant version of the function called strtok_r() where you pass in an extra argument which contains an allocated char * which the function will use instead of its own static storage for maintaining the tokenizing state. If you are using APR you can use apr_strtok().

crypt() is another function that tends to not be reentrant, so if you run across calls to that function in a library, watch out. On some systems it is reentrant though, so it is not always a problem. If your system has crypt_r() chances are you should be using that, or if possible simply avoid the whole mess by using md5 instead.

Common 3rd Party Libraries

The following is a list of common libraries that are used by 3rd party Apache modules. You can check to see if your module is using a potentially unsafe library by using tools such as ldd(1) and nm(1). For PHP, for example, try this:

% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

In addition to these libraries you will need to have a look at any libraries linked statically into the module. You can use nm(1) to look for individual symbols in the module.

Library List

Please drop a note to dev@httpd.apache.org if you have additions or corrections to this list.

Library | Version | Thread Safe? | Notes
ASpell/PSpell |  | ? |
Berkeley DB | 3.x, 4.x | Yes | Be careful about sharing a connection across threads.
bzip2 |  | Yes | Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.
cdb |  | ? |
C-Client |  | Perhaps | c-client uses strtok() and gethostbyname() which are not thread-safe on most C library implementations. c-client's static data is meant to be shared across threads. If strtok() and gethostbyname() are thread-safe on your OS, c-client may be thread-safe.
libcrypt |  | ? |
Expat |  | Yes | Need a separate parser instance per thread
FreeTDS |  | ? |
FreeType |  | ? |
GD 1.8.x |  | ? |
GD 2.0.x |  | ? |
gdbm |  | No | Errors returned via a static gdbm_error variable
ImageMagick | 5.2.2 | Yes | ImageMagick docs claim it is thread safe since version 5.2.2 (see Change log).
Imlib2 |  | ? |
libjpeg | v6b | ? |
libmysqlclient |  | Yes | Use mysqlclient_r library variant to ensure thread-safety. For more information, please read http://dev.mysql.com/doc/mysql/en/Threaded_clients.html.
Ming | 0.2a | ? |
Net-SNMP | 5.0.x | ? |
OpenLDAP | 2.1.x | Yes | Use ldap_r library variant to ensure thread-safety.
OpenSSL | 0.9.6g | Yes | Requires proper usage of CRYPTO_num_locks, CRYPTO_set_locking_callback, CRYPTO_set_id_callback
liboci8 (Oracle 8+) | 8.x,9.x | ? |
pdflib | 5.0.x | Yes | PDFLib docs claim it is thread safe; changes.txt indicates it has been partially thread-safe since V1.91: http://www.pdflib.com/products/pdflib-family/pdflib/.
libpng | 1.0.x | ? |
libpng | 1.2.x | ? |
libpq (PostgreSQL) | 8.x | Yes | Don't share connections across threads and watch out for crypt() calls
Sablotron | 0.95 | ? |
zlib | 1.1.4 | Yes | Relies upon thread-safe zalloc and zfree functions Default is to use libc's calloc/free which are thread-safe.


Terim Sözlüğü - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Terim Sözlüğü

Bu sözlük, genelinde HTML sayfa sunumuna, özelinde Apache HTTP Sunucusuna özgü ortak terminolojinin bir kısmını içerir. Her kavram ile ilgili daha ayrıntılı bilgi bağlarla sağlanmıştır.

Tanımlar

Algoritma
Bir sorunu sonlu sayıda adımda çözümlemek için uygulanan kurallar kümesi veya anlam belirsizliği içermeyen bir formül. Şifreleme için kullanılan algoritmalara şifre denir.
Aktarım Katmanı Güvenliği
İngilizcesi: Transport Layer Security (TLS)
TCP/IP ağları üzerinden genel iletişimin kimlik doğrulamalı ve şifreli yapılabilmesi için SSL’nin ardılı olarak Genel Ağ Mühendisliği Görev Gücü (IETF) tarafından oluşturulmuş protokol. TLS’nin 1. sürümü ile SSL’in 3. sürümü hemen hemen aynıdır.
Bakınız: SSL/TLS Şifrelemesi
Alt istek
Diğer dosya sistemlerini veya URL yollarını kısmen veya tamamen değerlendiren modüller için sunucuda bir alt istek API'si mevcuttur. Bu API'nin olası müşterileri için DirectoryIndex, mod_autoindex ve mod_include örnek verilebilir.
Anahtar Parolası
Özel anahtar dosyalarını yetkisiz kişilerden koruyan sözcük veya cümle. Genellikle sadece şifreler için kullanılan gizli şifreleme/şifre çözme anahtarını korur.
Bakınız: SSL/TLS Şifrelemesi
Apache Eklenti Aracı (apxs)
İngilizcesi: APache eXtension Tool - apxs
Modül kaynak kodlarının devinen paylaşımlı nesneler (DSO) halinde derlenmesine ve Apache Sunucusu içinde kurulmasına yardım eden bir Perl betiği.
Daha ayrıntılı bilgi için apxs kılavuz sayfasına bakınız.
Apache Taşınabilir Arayüzü (APR)
İngilizcesi: Apache Portable Runtime - APR
Sunucu ile işletim sistemi arasındaki temel arayüzleri oluşturan kütüphaneler kümesine verilen ad. APR, Apache HTTP Sunucusuna paralel bağımsız bir proje olarak geliştirilmektedir.
Bakınız: Apache Taşınabilir Arayüzü Projesi
Bağlam
Yapılandırma dosyalarında sadece belli türdeki yönergelerin bulunmasına izin verilen bir bölge.
Bakınız: Apache Yönergelerini Açıklamak için Kullanılan Terimler
Bakışımlı Şifreleme Tekniği
Şifreleme ve şifre çözme için tek bir anahtarın kullanıldığı bir şifreleme tekniği.
Bakınız: SSL/TLS Şifrelemesi
Başlık
Bir HTTP isteğinin parçası olarak, gönderilen yanıtta asıl içerikten önce yer alan ve içerik hakkında mecazlar içeren veri.
CONNECT
Ham veri kanallarını HTTP üzerinden yönlendirmek için kullanılan bir HTTP yöntemi. SSL protokolü gibi diğer protokolleri sarmalamakta kullanılabilir.
Devingen Paylaşımlı Nesne (DSO)
İngilizcesi: Dynamic Shared Object (DSO)
İstek halinde yüklenebilen, Apache httpd çalıştırılabilir dosyasından ayrı olarak derlenmiş modüllerin ortak adı.
Bakınız: Devingen Paylaşımlı Nesne Desteği
Düz Metin
Şifrelenmemiş metin.
Düzenli İfade (Regex)
Metin içinde bir şablon tanımlama yolu. Örneğin, “A harfi ile başlayan bütün sözcükler” veya “10 rakamlı telefon numaraları” ya da “Baş harfi Z olmayan ve iki virgül içeren cümleler” gibi. Düzenli ifadeler, Apache’de belli özniteliklere uygun dosya veya özkaynakları toplamak için esnek bir yol sağlamasından ötürü oldukça yararlıdır. Örneğin, “resimler” dizini altındaki dosyalardan .gif ve .jpg uzantılı olanları toplamak için “/resimler/.*(jpg|gif)$” düzenli ifadesi yazılabilir. Dizgileri değiştirmek için düzenli ifadelerin kullanıldığı yerlerde, eşleşen (parantezlerin içinde) gruplanmış parçalara başvurmak için $1 ... $9 özel değişkenleri kullanılır. $0 özel değişkeni eşleşen ifadenin tamamına karşılık gelir. Bir dizgi içinde $ işaretini kendisi olarak kullanmak isterseniz önüne bir \ imi koymalısınız. Geçmişe uyumluluk adına bazı yerlerde $0 yerine & değişkeni kullanılabilir. Ancak 2.3.6 sürümünden beri bu artık mümkün değildir. Apache, PCRE kütüphanesi ile sağlanan Perl uyumlu düzenli ifadeleri kullanır. PCRE düzenli ifadelerinin sözdizimi ile ilgili ayrıntılı bilgiyi Wikipedia'da bulabilirsiniz.
Erişim Denetimi
Ağ bölgelerine erişimin kısıtlanması. Apache bağlamında normal olarak belli URL’lere erişimi kısıtlamak şeklinde uygulanır.
Bakınız: Kimlik Doğrulama, Yetkilendirme ve Erişim Denetimi
Eylemci
Bir dosya istendiğinde uygulanacak eylemi Apache içinde gerçekleştiren nesne. Genellikle dosyalar, dosya türüne bağlı dolaylı eylemcilere sahiptir. Normalde tüm dosyalar sunucu tarafından sıradan birer dosya olarak işleme sokulduğu halde bazı belli dosyalar diğerlerinden ayrı ele alınır. Örneğin, cgi-script eylemcisi dosyaları CGI’ler tarafından işlenebilir hale getirmek üzere işleme sokar.
Bakınız: Apache Eylemcilerinin Kullanımı
Genel Anahtar
Genel Anahtarlı Şifreleme Tekniğinde, sahibinin yaptığı imzaları çözmeye ve sahibine gönderilen iletileri şifrelemeye yarayan genel erişime açık anahtar.
Bakınız: SSL/TLS Şifrelemesi
Genel Anahtarlı Şifreleme Tekniği
Şifreleme ve şifre çözme için iki ayrı anahtarın kullanıldığı bakışımsız şifreleme sistemlerinin konusu veya uygulaması. Bu amaçla kullanılan anahtarlar bir anahtar çiftinden oluşur. Genel Anahtarlı Şifrelemeye Bakışımsız Şifreleme de denir.
Bakınız: SSL/TLS Şifrelemesi
Gizli Anahtar
Genel Anahtarlı Şifreleme Tekniğinde, giden iletileri imzalamak ve gelen iletilerin şifrelerini çözmek amacıyla kullanılan gizli anahtar.
Bakınız: SSL/TLS Şifrelemesi
Güvenli Hiper Metin Aktarım Protokolü (HTTPS)
İngilizcesi: The HyperText Transfer Protocol (Secure), (HTTPS)
Güvenli Hiper Metin Aktarım Protokolü, Genel Ağ’da kullanılan standart şifreli iletişim mekanizmasıdır. Aslında HTTP protokolünün SSL üzerinden gerçekleştirilmesinden başka bir şey değildir.
Bakınız: SSL/TLS Şifrelemesi
Güvenli Soket Katmanı
İngilizcesi: Secure Sockets Layer (SSL)
TCP/IP ağları üzerinden genel iletişimin kimlik doğrulamalı ve şifreli yapılabilmesi için Netscape Communications Corporation tarafından oluşturulmuş bir protokol. Günümüzde en çok HTTPS, yani SSL üzerinden Hiper Metin Aktarım Protokolü şeklinde kullanılmaktadır.
Bakınız: SSL/TLS Şifrelemesi
Hiper Metin Aktarım Protokolü (HTTP)
İngilizcesi: HyperText Transfer Protocol (HTTP)
Genel Ağ’da kullanılan standart aktarım protokollerinden biri. Apache, RFC 2616 ile tanımlanmış protokolün HTTP/1.1 olarak bilinen 1.1 sürümünü gerçekler.
.htaccess
Belge dosyaları ağacı içine yerleştirilen bir yapılandırma dosyası olup yerleştiği dizine ve o dizinin alt dizinlerine yapılandırma yönergeleri uygulanmasını sağlar. İsmine rağmen böyle bir dosyanın içerebileceği yönergeler erişim denetleme yönergeleri ile sınırlı değildir; hemen her tür yönergeyi içerebilir.
Bakınız: Yapılandırma Dosyaları
httpd.conf
Ana Apache yapılandırma dosyası. Dosya sistemindeki öntanımlı yeri /usr/local/apache2/conf/httpd.conf olup derleme sırasındaki yapılandırmayla veya çalışma anındaki yapılandırmayla başka bir yer belirtilebilir.
Bakınız: Yapılandırma Dosyaları
İhracat Engelli
İngilizcesi: Export-Crippled
Amerika Birleşik Devletlerinin İhracat Yönetim Düzenlemelerine (EAR) uymak için şifreleme yoluyla sakatlanmış yazılım. İhracat engelli olması için şifrelenmiş yazılımları birer şifreli metin haline getiren şifre anahtarları küçük boyutlu olduğundan şifreleme zor kullanılarak kırılabilir.
Bakınız: SSL/TLS Şifrelemesi
İleti Özeti
İngilizcesi: Message Digest
Aktarım sırasında içeriğinin değişme olasılığı bulunan bir iletinin içeriğini doğrulamak için kullanılan bir özet.
Bakınız: SSL/TLS Şifrelemesi
Karşı Vekil
İstemciye kendini asıl sunucu imiş gibi gösteren bir vekil sunucu. Güvenlik, yük dengelemesi gibi sebeplerle asıl sunucuyu istemcilerden gizlemek için yararlıdır.
Kimlik Doğrulama
Sunucu, istemci veya kullanıcı gibi bir ağ öğesinin kimliğinin olumlanması.
Bakınız: Kimlik Doğrulama, Yetkilendirme ve Erişim Denetimi
MIME türü
Aktarılan belgenin çeşidini betimlemenin bir yolu. MIME, Türkçe’ye ‘Çok Amaçlı Genel Ağ Posta Eklentileri’ olarak çevrilebilecek olan "Multipurpose Internet Mail Extensions" sözcüklerinden türetilmiş bir kısaltmadır. MIME türleri bir bölü çizgisi ile ayrılmış bir ana ve bir alt belge türünün birleşiminden oluşur. text/html, image/gif ve application/octet-stream örnek olarak verilebilir. HTTP protokolünde MIME türleri Content-Type başlığında aktarılır.
Bakınız: mod_mime
Modül
Bir programın bağımsız parçalarından her biri. Apache işlevselliğinin çoğu yapılandırmaya dahil edilip edilmeyeceğine kullanıcı tarafından karar verilebilen modüllerden oluşur. Apache httpd çalıştırılabiliri içinde derlenmiş modüllere durağan modüller adı verilirken ayrı bir yerde saklanan ve çalışma anında isteğe bağlı olarak yüklenebilen modüllere devingen modüller veya DSO’lar denir. Yapılandırmaya öntanımlı olarak dahil edilen modüllere temel modüller denir. Apache için kullanılabilecek modüllerin çoğu Apache HTTP Sunucusunun tar paketi içinde dağıtılmaz; bunlara üçüncü parti modüller denir.
Bakınız: Modül Dizini
OpenSSL
SSL/TLS için açık kaynak kodlu araç kiti.
Daha ayrıntılı bilgi için http://www.openssl.org/ adresine bakınız.
Ortak Ağgeçidi Arayüzü (CGI)
İngilizcesi: Common Gateway Interface (CGI)
Bir HTTP sunucusunun bir harici programa hizmet istekleri yapmasını mümkün kılan, sunucu ile bir harici program arasındaki bir arayüz standardı. Özellikleri kapsayan bir Bilgilendirici RFC vardır.
Bakınız: CGI ile Devingen İçerik
Ortam Değişkeni (ortam-değişkeni)
İşletim sistemi kabuğu tarafından yönetilen ve programlar arasında bilgi alışverişi amacıyla kullanılan isimli değişkenler. Ayrıca, Apache de ortam değişkenleri olarak tanımlanabilecek dahili değişkenler içerir fakat bunlar kabuk ortamında değil dahili Apache yapıları içinde saklanır.
Bakınız: Apache Ortam Değişkenleri
Oturum
Bir iletişimin bağlamsal bilgileri.
Özet
Uzunluğu değişebilen bir dizgenin belli bir durumuna ilişkin sabit uzunlukta bir dizge üretmek için kullanılan geri dönüşümsüz bir algoritma. Algoritmaya girdi olan farklı uzunluktaki dizgeler (özet işlevine bağlı olarak) aynı uzunlukta farklı özetler üretir.
Sanal Konaklık
Tek bir Apache sunucusundan çok sayıda site sunulması. IP tabanlı sanal konaklıkta siteler birbirlerinden IP adreslerine göre ayrılırken, isim tabanlı sanal konaklıkta siteler aynı IP adresinden kendi isimleriyle sunulabilirler.
Bakınız: Apache Sanal Konak Belgeleri
Sayısal İmza
Bir sertifikayı veya bir dosyayı doğrulamakta kullanılan şifreli bir metin. Bir imza Sertifika Makamı tarafından bir sertifikaya gömülü olan genel anahtardan bir özet üretilerek oluşturulur. İmza şifresi sadece sertifika sahibi ağ öğesinin kimliğini doğrulayacak SM’nin genel anahtarı kullanılarak çözülebilir.
Bakınız: SSL/TLS Şifrelemesi
Sertifika
Sunucu, istemci gibi ağ öğelerinin kimliğini kanıtlamakta kullanılan bir veri kaydı. Bir sertifika, sertifika sahibi (buna sertifikanın konusu da denir), sertifikayı imzalayan Sertifika Makamı (SM) (buna sertifika yayıncısı da denir), sertifika sahibinin genel anahtarı ve SM tarafından üretilen imza gibi parçalardan oluşan X.509 bilgisi içerir. Ağ öğeleri bu imzaları SM sertifikalarını kullanarak doğrular.
Bakınız: SSL/TLS Şifrelemesi
Sertifika İmzalama İsteği (Sİİ)
İngilizcesi: Certificate Signing Request (CSR)
İmzasız bir sertifikayı Sertifika Makamına kendi SM Sertifikasının özel anahtarı ile imzalaması için yapılan istek. Sİİ imzalanınca bir gerçek sertifika haline gelir.
Bakınız: SSL/TLS Şifrelemesi
Sertifika Makamı (SM)
İngilizcesi: Certification Authority (CA)
Ağ öğelerinin güvenilir olarak kimliklerinin doğrulanması için sertifikaları imzalayan güvenilir üçüncü şahıs. Diğer ağ öğeleri, sertifikalı bir öğenin kimliğini kanıtlayan bir SM’yi doğrulamak için imzayı sınayabilir.
Bakınız: SSL/TLS Şifrelemesi
Sihirli Modül Numarası (SMN)
Sihirli Modül Numarası, modüllerin ikil uyumluluğu ile ilgili olarak Apache kaynak kodunda tanımlanmış bir sabittir. Apache dahili yapıları, uygulama programlama arayüzünün önemli parçaları ve işlev çağrıları artık ikil uyumluluğun garanti edilemeyeceği kadar değiştiği zaman SMN değiştirilir. Bir SMN değişikliğinde ve bazen de sırf yeni bir Apache sürümü ile çalışmak icabettiğinde tüm üçüncü parti modüllerin en azından yeniden derlenmesi gerekir.
SSLeay
Eric A. Young tarafından geliştirilmiş özgün SSL/TLS gerçeklenim kütüphanesi.
Sunucu Adı Belirtimi
İngilizcesi: Server Name Indication (SNI)
İlk SSL uzlaşımı sırasında istenen sunucu isminin aktarılmasını mümkün kılan bir SSL işlevidir. Böylece sunucunun, SSL uzlaşım işlemlerlerinde kullanılacak sanal konak yapılandırmasını doğru bir şekilde seçebilmesi sağlanmıştır. Bu özellik RFC 3546'da TLS eklentili SSL başlatma bölümüne eklenmiştir.
Bakınız: SSL SSS ve RFC 3546
Sunucu Taraflı İçerik Yerleştirme
İngilizcesi: Server Side Includes (SSI)
İşlem yönergelerini HTML dosyalara gömme tekniği.
Bakınız: Sunucu Taraflı İçerik Yerleştirmeye Giriş
Süzgeç
Sunucu tarafından alınan ve gönderilen veriye uygulanan bir işlem. Giriş süzgeçleri sunucuya istemci tarafından gönderilen veriyi işlerken çıkış süzgeçleri sunucu tarafından istemciye gönderilen belgeleri işler. Örneğin, INCLUDES çıkış süzgeci, belgeleri sunucu taraflı içerik için işleme sokar.
Bakınız: Süzgeçler
Şifre
Veri şifrelemek için kullanılan bir algoritma veya sistem. DES, IDEA veya RC4 örnek verilebilir.
Bakınız: SSL/TLS Şifrelemesi
Şifreli Metin
Bir Düz Metin bir Şifreden geçirilince elde edilen sonuç.
Bakınız: SSL/TLS Şifrelemesi
Tam Alan Adı (TAA)
İngilizcesi: Fully-Qualified Domain-Name (FQDN)
Bir IP adresiyle eşleşebilen, bir konak adıyla bir alan adının birleşiminden oluşan eşsiz bir ağ öğesi ismi. Örneğin, httpd.apache.org tam alan adında httpd bir konak adıyken apache.org bir alan adıdır.
Tar Paketi
tar uygulaması kullanılarak bir araya getirilmiş dosyalardan oluşan bir paket. Apache dağıtımları sıkıştırılmış tar arşivleri içinde veya pkzip kullanılarak saklanır.
Tektip Özkaynak Betimleyici
İngilizcesi: Uniform Resource Identifier (URI)
Soyut veya somut bir özkaynağı betimlemek için kullanılan bütünleşik bir karakter dizisi. Aslen RFC 2396 tarafından tanımlanmıştır. Genel Ağ’da kullanılan URI’lerden genellikle URL’ler olarak bahsedilir.
Tektip Özkaynak Konumlayıcı
İngilizcesi: Uniform Resource Locator (URL)
Genel Ağ üzerindeki bir özkaynağın ismi veya adresi. Aslen Tektip Özkaynak Betimleyici denilen terimin gayrı resmi karşılığıdır. URL’ler http veya https gibi bir şemayı takip eden bir konak adı ve bir dosya yolundan oluşurlar. Örneğin, bu sayfanın URL’si http://httpd.apache.org/docs/2.4/glossary.html olurdu.
Vekil
Asıl sunucu ile istemci arasında aracılık yapan sunucu. İstemciden aldığı istekleri asıl sunucuya gönderip, ondan aldığı yanıtları istemciye gönderir. Aynı içeriğe birden fazla istemci talip olursa vekil sunucu bu istekleri her seferinde asıl sunucudan istemek yerine kendi deposundan karşılar, böylece yanıt zamanı kısalır.
Bakınız: mod_proxy
Yapılandırma Dosyası
Apache yapılandırmasını denetim altına alan yönergeleri içeren bir metin dosyası.
Bakınız: Yapılandırma Dosyaları
Yapılandırma Yönergesi
Bakınız: Yönerge
Yönerge
Belli Apache davranışlarından bir veya daha fazlasını denetim altına alan bir yapılandırma komutu. Yönergeler yapılandırma dosyalarına yerleştirilir.
Bakınız: Yönerge Dizini
Yöntem
HTTP bağlamında, istemci tarafından istek satırında belirtilen, bir özkaynağa uygulanacak bir eylem. HTTP bağlamında belirtilebilecek yöntemlere örnek olarak GET, POST ve PUT verilebilir.
X.509
SSL/TLS kimlik doğrulamasında kullanılmak üzere Uluslararası Telekom Birliği (ITU-T) tarafından önerilmiş bir kimlik doğrulama sertitifası şeması
Bakınız: SSL/TLS Şifrelemesi

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Modül Dizini - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Modül Dizini

Apache HTTP Sunucusu dağıtımının parçası olarak gelen modüllerin tamamı aşağıda listelenmiştir. Ayrıca, tüm Apache HTTP Sunucusu yönergelerinin alfabetik olarak listelendiği bir Yönerge Dizini de mevcuttur.

Ayrıca bakınız:

  • Çok Süreçlilik Modülleri (MPM’ler)
  • Hızlı Yönerge Kılavuzu

Temel Özellikler ve Çoklu İşlem Modülleri

core
Apache HTTP Sunucusunda daima mevcut olan çekirdek özellikler
mpm_common
Birden fazla Çok Süreçlilik Modülü (MPM) tarafından gerçeklenmiş yönergeler bütünü.
event
A variant of the worker MPM with the goal of consuming threads only for connections with active processing
mpm_netware
Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
mpmt_os2
Hybrid multi-process, multi-threaded MPM for OS/2
prefork
Evresiz ön çatallamalı HTTP sunucusu oluşturur
mpm_winnt
Multi-Processing Module optimized for Windows NT.
worker
Çok evreli ve çok süreçli melez bir HTTP sunucusu oluşturan çok süreçlilik modülü.

Diğer Modüller

A | B | C | D | E | F | H | I | L | M | N | P | R | S | U | V | W | X

mod_access_compat
Group authorizations based on host (name or IP address)
mod_actions
Execute CGI scripts based on media type or request method.
mod_alias
Belge ağacının parçalarının dosya sisteminin parçalarıyla eşlenmesini sağlar ve URL yönlendirmesi yapar.
mod_allowmethods
Easily restrict what HTTP methods can be used on the server
mod_asis
Sends files that contain their own HTTP headers
mod_auth_basic
Basic HTTP authentication
mod_auth_digest
User authentication using MD5 Digest Authentication
mod_auth_form
Form authentication
mod_authn_anon
Allows "anonymous" user access to authenticated areas
mod_authn_core
Core Authentication
mod_authn_dbd
User authentication using an SQL database
mod_authn_dbm
User authentication using DBM files
mod_authn_file
User authentication using text files
mod_authn_socache
Manages a cache of authentication credentials to relieve the load on backends
mod_authnz_fcgi
Allows a FastCGI authorizer application to handle Apache httpd authentication and authorization
mod_authnz_ldap
Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
mod_authz_core
Core Authorization
mod_authz_dbd
Group Authorization and Login using SQL
mod_authz_dbm
Group authorization using DBM files
mod_authz_groupfile
Group authorization using plaintext files
mod_authz_host
Group authorizations based on host (name or IP address)
mod_authz_owner
Authorization based on file ownership
mod_authz_user
User Authorization
mod_autoindex
Unix ls veya Win32 dir kabuk komutunun yaptığı gibi dizin içeriğini listeler.
mod_buffer
Support for request buffering
mod_cache
RFC 2616 compliant HTTP caching filter.
mod_cache_disk
Disk based storage module for the HTTP caching filter.
mod_cache_socache
Shared object cache (socache) based storage module for the HTTP caching filter.
mod_cern_meta
CERN httpd metafile semantics
mod_cgi
Execution of CGI scripts
mod_cgid
Execution of CGI scripts using an external CGI daemon
mod_charset_lite
Specify character set translation or recoding
mod_data
Convert response body into an RFC2397 data URL
mod_dav
Distributed Authoring and Versioning (WebDAV) functionality
mod_dav_fs
Filesystem provider for mod_dav
mod_dav_lock
Generic locking module for mod_dav
mod_dbd
Manages SQL database connections
mod_deflate
Compress content before it is delivered to the client
mod_dialup
Send static content at a bandwidth rate limit, defined by the various old modem standards
mod_dir
Bölü çizgisiyle biten yönlendirmeleri yapar ve dizin içeriği dosyalarını sunar.
mod_dumpio
Dumps all I/O to error log as desired.
mod_echo
A simple echo server to illustrate protocol modules
mod_env
CGI betiklerine ve SSI sayfalarına aktarılan değişkenlere müdahale etmek için kullanılır.
mod_example_hooks
Illustrates the Apache module API
mod_expires
Generation of Expires and Cache-Control HTTP headers according to user-specified criteria
mod_ext_filter
Pass the response body through an external program before delivery to the client
mod_file_cache
Caches a static list of files in memory
mod_filter
Context-sensitive smart filter configuration module
mod_headers
Customization of HTTP request and response headers
mod_heartbeat
Sends messages with server status to frontend proxy
mod_heartmonitor
Centralized monitor for mod_heartbeat origin servers
mod_http2
Support for the HTTP/2 transport layer
mod_ident
RFC 1413 ident lookups
mod_imagemap
Server-side imagemap processing
mod_include
Server-parsed html documents (Server Side Includes)
mod_info
Provides a comprehensive overview of the server configuration
mod_isapi
ISAPI Extensions within Apache for Windows
mod_lbmethod_bybusyness
Pending Request Counting load balancer scheduler algorithm for mod_proxy_balancer
mod_lbmethod_byrequests
Request Counting load balancer scheduler algorithm for mod_proxy_balancer
mod_lbmethod_bytraffic
Weighted Traffic Counting load balancer scheduler algorithm for mod_proxy_balancer
mod_lbmethod_heartbeat
Heartbeat Traffic Counting load balancer scheduler algorithm for mod_proxy_balancer
mod_ldap
LDAP connection pooling and result caching services for use by other LDAP modules
mod_log_config
Sunucuya yapılan isteklerin günlük kayıtlarının tutulması
mod_log_debug
Additional configurable debug logging
mod_log_forensic
Sunucuya yapılan isteklerin adli günlük kayıtlarının tutulması
mod_logio
Her isteğin girdi ve çıktı uzunluklarının günlüklenmesi.
mod_lua
Provides Lua hooks into various portions of the httpd request processing
mod_macro
Provides macros within apache httpd runtime configuration files
mod_mime
Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding)
mod_mime_magic
Determines the MIME type of a file by looking at a few bytes of its contents
mod_negotiation
Provides for content negotiation
mod_nw_ssl
Enable SSL encryption for NetWare
mod_privileges
Support for Solaris privileges and for running virtual hosts under different user IDs.
mod_proxy
Multi-protocol proxy/gateway server
mod_proxy_ajp
AJP support module for mod_proxy
mod_proxy_balancer
mod_proxy extension for load balancing
mod_proxy_connect
mod_proxy extension for CONNECT request handling
mod_proxy_express
Dynamic mass reverse proxy extension for mod_proxy
mod_proxy_fcgi
FastCGI support module for mod_proxy
mod_proxy_fdpass
fdpass external process support module for mod_proxy
mod_proxy_ftp
FTP support module for mod_proxy
mod_proxy_html
Rewrite HTML links in to ensure they are addressable from Clients' networks in a proxy context.
mod_proxy_http
HTTP support module for mod_proxy
mod_proxy_scgi
SCGI gateway module for mod_proxy
mod_proxy_wstunnel
Websockets support module for mod_proxy
mod_ratelimit
Bandwidth Rate Limiting for Clients
mod_reflector
Reflect a request body as a response via the output filter stack.
mod_remoteip
Replaces the original client IP address for the connection with the useragent IP address list presented by a proxies or a load balancer via the request headers.
mod_reqtimeout
Set timeout and minimum data rate for receiving requests
mod_request
HTTP istek gövdelerini işleme sokup kullanılabilir kılan süzgeçler
mod_rewrite
Provides a rule-based rewriting engine to rewrite requested URLs on the fly
mod_sed
Filter Input (request) and Output (response) content using sed syntax
mod_session
Session support
mod_session_cookie
Cookie based session support
mod_session_crypto
Session encryption support
mod_session_dbd
DBD/SQL based session support
mod_setenvif
Ortam değişkenlerinin isteğin özelliklerine uygun olarak atanmasını sağlar
mod_slotmem_plain
Slot-based shared memory provider.
mod_slotmem_shm
Slot-based shared memory provider.
mod_so
Modüllerin ve çalıştırılabilir kodun sunucunun başlatılması veya yeniden başlatılması sırasında yüklenmesini sağlar.
mod_socache_dbm
DBM based shared object cache provider.
mod_socache_dc
Distcache based shared object cache provider.
mod_socache_memcache
Memcache based shared object cache provider.
mod_socache_shmcb
shmcb based shared object cache provider.
mod_speling
Attempts to correct mistaken URLs by ignoring capitalization, or attempting to correct various minor misspellings.
mod_ssl
Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
mod_status
Sunucu etkinliği ve başarımı hakkında bilgi sağlar.
mod_substitute
Perform search and replace operations on response bodies
mod_suexec
CGI betiklerinin belli bir kullanıcı ve grubun aidiyetinde çalışmasını mümkün kılar.
mod_unique_id
Provides an environment variable with a unique identifier for each request
mod_unixd
Unix ailesi platformlar için temel (gerekli) güvenlik.
mod_userdir
Kullanıcılara özel dizinler
mod_usertrack
Clickstream logging of user activity on a site
mod_version
Version dependent configuration
mod_vhost_alias
Kitlesel sanal konakların devingen olarak yapılandırılmasını sağlar
mod_watchdog
provides infrastructure for other modules to periodically run tasks
mod_xml2enc
Enhanced charset/internationalisation support for libxml2-based filter modules

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Yönerge Dizini - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Yönerge Dizini

Standart Apache dağıtımında bulunan yönergelerin tamamı burada listelenmiştir. Hepsi aralarında şekilsel bir uyum sağlanarak açıklanmışlardır. Açıklamalarında kullanılan terimler için Yönerge Sözlüğüne bakabilirsiniz.

Ayrıca, yönerge ayrıntılarının bir özet olarak listelendiği bir Hızlı Yönerge Kılavuzu da mevcuttur.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | Q | R | S | T | U | V | W | X

  • AcceptFilter
  • AcceptPathInfo
  • AccessFileName
  • Action
  • AddAlt
  • AddAltByEncoding
  • AddAltByType
  • AddCharset
  • AddDefaultCharset
  • AddDescription
  • AddEncoding
  • AddHandler
  • AddIcon
  • AddIconByEncoding
  • AddIconByType
  • AddInputFilter
  • AddLanguage
  • AddModuleInfo
  • AddOutputFilter
  • AddOutputFilterByType
  • AddType
  • Alias
  • AliasMatch
  • Allow
  • AllowCONNECT
  • AllowEncodedSlashes
  • AllowMethods
  • AllowOverride
  • AllowOverrideList
  • Anonymous
  • Anonymous_LogEmail
  • Anonymous_MustGiveEmail
  • Anonymous_NoUserID
  • Anonymous_VerifyEmail
  • AsyncRequestWorkerFactor
  • AuthBasicAuthoritative
  • AuthBasicFake
  • AuthBasicProvider
  • AuthBasicUseDigestAlgorithm
  • AuthDBDUserPWQuery
  • AuthDBDUserRealmQuery
  • AuthDBMGroupFile
  • AuthDBMType
  • AuthDBMUserFile
  • AuthDigestAlgorithm
  • AuthDigestDomain
  • AuthDigestNonceLifetime
  • AuthDigestProvider
  • AuthDigestQop
  • AuthDigestShmemSize
  • AuthFormAuthoritative
  • AuthFormBody
  • AuthFormDisableNoStore
  • AuthFormFakeBasicAuth
  • AuthFormLocation
  • AuthFormLoginRequiredLocation
  • AuthFormLoginSuccessLocation
  • AuthFormLogoutLocation
  • AuthFormMethod
  • AuthFormMimetype
  • AuthFormPassword
  • AuthFormProvider
  • AuthFormSitePassphrase
  • AuthFormSize
  • AuthFormUsername
  • AuthGroupFile
  • AuthLDAPAuthorizePrefix
  • AuthLDAPBindAuthoritative
  • AuthLDAPBindDN
  • AuthLDAPBindPassword
  • AuthLDAPCharsetConfig
  • AuthLDAPCompareAsUser
  • AuthLDAPCompareDNOnServer
  • AuthLDAPDereferenceAliases
  • AuthLDAPGroupAttribute
  • AuthLDAPGroupAttributeIsDN
  • AuthLDAPInitialBindAsUser
  • AuthLDAPInitialBindPattern
  • AuthLDAPMaxSubGroupDepth
  • AuthLDAPRemoteUserAttribute
  • AuthLDAPRemoteUserIsDN
  • AuthLDAPSearchAsUser
  • AuthLDAPSubGroupAttribute
  • AuthLDAPSubGroupClass
  • AuthLDAPUrl
  • AuthMerging
  • AuthName
  • AuthnCacheContext
  • AuthnCacheEnable
  • AuthnCacheProvideFor
  • AuthnCacheSOCache
  • AuthnCacheTimeout
  • <AuthnProviderAlias>
  • AuthnzFcgiCheckAuthnProvider
  • AuthnzFcgiDefineProvider
  • AuthType
  • AuthUserFile
  • AuthzDBDLoginToReferer
  • AuthzDBDQuery
  • AuthzDBDRedirectQuery
  • AuthzDBMType
  • <AuthzProviderAlias>
  • AuthzSendForbiddenOnFailure
  • BalancerGrowth
  • BalancerInherit
  • BalancerMember
  • BalancerPersist
  • BrowserMatch
  • BrowserMatchNoCase
  • BufferedLogs
  • BufferSize
  • CacheDefaultExpire
  • CacheDetailHeader
  • CacheDirLength
  • CacheDirLevels
  • CacheDisable
  • CacheEnable
  • CacheFile
  • CacheHeader
  • CacheIgnoreCacheControl
  • CacheIgnoreHeaders
  • CacheIgnoreNoLastMod
  • CacheIgnoreQueryString
  • CacheIgnoreURLSessionIdentifiers
  • CacheKeyBaseURL
  • CacheLastModifiedFactor
  • CacheLock
  • CacheLockMaxAge
  • CacheLockPath
  • CacheMaxExpire
  • CacheMaxFileSize
  • CacheMinExpire
  • CacheMinFileSize
  • CacheNegotiatedDocs
  • CacheQuickHandler
  • CacheReadSize
  • CacheReadTime
  • CacheRoot
  • CacheSocache
  • CacheSocacheMaxSize
  • CacheSocacheMaxTime
  • CacheSocacheMinTime
  • CacheSocacheReadSize
  • CacheSocacheReadTime
  • CacheStaleOnError
  • CacheStoreExpired
  • CacheStoreNoStore
  • CacheStorePrivate
  • CGIDScriptTimeout
  • CGIMapExtension
  • CGIPassAuth
  • CharsetDefault
  • CharsetOptions
  • CharsetSourceEnc
  • CheckCaseOnly
  • CheckSpelling
  • ChrootDir
  • ContentDigest
  • CookieDomain
  • CookieExpires
  • CookieName
  • CookieStyle
  • CookieTracking
  • CoreDumpDirectory
  • CustomLog
  • Dav
  • DavDepthInfinity
  • DavGenericLockDB
  • DavLockDB
  • DavMinTimeout
  • DBDExptime
  • DBDInitSQL
  • DBDKeep
  • DBDMax
  • DBDMin
  • DBDParams
  • DBDPersist
  • DBDPrepareSQL
  • DBDriver
  • DefaultIcon
  • DefaultLanguage
  • DefaultRuntimeDir
  • DefaultType
  • Define
  • DeflateBufferSize
  • DeflateCompressionLevel
  • DeflateFilterNote
  • DeflateInflateLimitRequestBody
  • DeflateInflateRatioBurst
  • DeflateInflateRatioLimit
  • DeflateMemLevel
  • DeflateWindowSize
  • Deny
  • <Directory>
  • DirectoryCheckHandler
  • DirectoryIndex
  • DirectoryIndexRedirect
  • <DirectoryMatch>
  • DirectorySlash
  • DocumentRoot
  • DTracePrivileges
  • DumpIOInput
  • DumpIOOutput
  • <Else>
  • <ElseIf>
  • EnableExceptionHook
  • EnableMMAP
  • EnableSendfile
  • Error
  • ErrorDocument
  • ErrorLog
  • ErrorLogFormat
  • Example
  • ExpiresActive
  • ExpiresByType
  • ExpiresDefault
  • ExtendedStatus
  • ExtFilterDefine
  • ExtFilterOptions
  • FallbackResource
  • FileETag
  • <Files>
  • <FilesMatch>
  • FilterChain
  • FilterDeclare
  • FilterProtocol
  • FilterProvider
  • FilterTrace
  • ForceLanguagePriority
  • ForceType
  • ForensicLog
  • GlobalLog
  • GprofDir
  • GracefulShutdownTimeout
  • Group
  • H2Direct
  • H2KeepAliveTimeout
  • H2MaxSessionStreams
  • H2MaxWorkerIdleSeconds
  • H2MaxWorkers
  • H2MinWorkers
  • H2ModernTLSOnly
  • H2Push
  • H2PushDiarySize
  • H2PushPriority
  • H2SerializeHeaders
  • H2SessionExtraFiles
  • H2StreamMaxMemSize
  • H2StreamTimeout
  • H2Timeout
  • H2TLSCoolDownSecs
  • H2TLSWarmUpSize
  • H2Upgrade
  • H2WindowSize
  • Header
  • HeaderName
  • HeartbeatAddress
  • HeartbeatListen
  • HeartbeatMaxServers
  • HeartbeatStorage
  • HeartbeatStorage
  • HostnameLookups
  • IdentityCheck
  • IdentityCheckTimeout
  • <If>
  • <IfDefine>
  • <IfModule>
  • <IfVersion>
  • ImapBase
  • ImapDefault
  • ImapMenu
  • Include
  • IncludeOptional
  • IndexHeadInsert
  • IndexIgnore
  • IndexIgnoreReset
  • IndexOptions
  • IndexOrderDefault
  • IndexStyleSheet
  • InputSed
  • ISAPIAppendLogToErrors
  • ISAPIAppendLogToQuery
  • ISAPICacheFile
  • ISAPIFakeAsync
  • ISAPILogNotSupported
  • ISAPIReadAheadBuffer
  • KeepAlive
  • KeepAliveTimeout
  • KeptBodySize
  • LanguagePriority
  • LDAPCacheEntries
  • LDAPCacheTTL
  • LDAPConnectionPoolTTL
  • LDAPConnectionTimeout
  • LDAPLibraryDebug
  • LDAPOpCacheEntries
  • LDAPOpCacheTTL
  • LDAPReferralHopLimit
  • LDAPReferrals
  • LDAPRetries
  • LDAPRetryDelay
  • LDAPSharedCacheFile
  • LDAPSharedCacheSize
  • LDAPTimeout
  • LDAPTrustedClientCert
  • LDAPTrustedGlobalCert
  • LDAPTrustedMode
  • LDAPVerifyServerCert
  • <Limit>
  • <LimitExcept>
  • LimitInternalRecursion
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldSize
  • LimitRequestLine
  • LimitXMLRequestBody
  • Listen
  • ListenBackLog
  • ListenCoresBucketsRatio
  • LoadFile
  • LoadModule
  • <Location>
  • <LocationMatch>
  • LogFormat
  • LogIOTrackTTFB
  • LogLevel
  • LogMessage
  • LuaAuthzProvider
  • LuaCodeCache
  • LuaHookAccessChecker
  • LuaHookAuthChecker
  • LuaHookCheckUserID
  • LuaHookFixups
  • LuaHookInsertFilter
  • LuaHookLog
  • LuaHookMapToStorage
  • LuaHookTranslateName
  • LuaHookTypeChecker
  • LuaInherit
  • LuaInputFilter
  • LuaMapHandler
  • LuaOutputFilter
  • LuaPackageCPath
  • LuaPackagePath
  • LuaQuickHandler
  • LuaRoot
  • LuaScope
  • <Macro>
  • MaxConnectionsPerChild
  • MaxKeepAliveRequests
  • MaxMemFree
  • MaxRangeOverlaps
  • MaxRangeReversals
  • MaxRanges
  • MaxRequestWorkers
  • MaxSpareServers
  • MaxSpareThreads
  • MaxThreads
  • MemcacheConnTTL
  • MergeTrailers
  • MetaDir
  • MetaFiles
  • MetaSuffix
  • MimeMagicFile
  • MinSpareServers
  • MinSpareThreads
  • MMapFile
  • ModemStandard
  • ModMimeUsePathInfo
  • MultiviewsMatch
  • Mutex
  • NameVirtualHost
  • NoProxy
  • NWSSLTrustedCerts
  • NWSSLUpgradeable
  • Options
  • Order
  • OutputSed
  • PassEnv
  • PidFile
  • PrivilegesMode
  • Protocol
  • ProtocolEcho
  • Protocols
  • ProtocolsHonorOrder
  • <Proxy>
  • ProxyAddHeaders
  • ProxyBadHeader
  • ProxyBlock
  • ProxyDomain
  • ProxyErrorOverride
  • ProxyExpressDBMFile
  • ProxyExpressDBMType
  • ProxyExpressEnable
  • ProxyFtpDirCharset
  • ProxyFtpEscapeWildcards
  • ProxyFtpListOnWildcard
  • ProxyHTMLBufSize
  • ProxyHTMLCharsetOut
  • ProxyHTMLDocType
  • ProxyHTMLEnable
  • ProxyHTMLEvents
  • ProxyHTMLExtended
  • ProxyHTMLFixups
  • ProxyHTMLInterp
  • ProxyHTMLLinks
  • ProxyHTMLMeta
  • ProxyHTMLStripComments
  • ProxyHTMLURLMap
  • ProxyIOBufferSize
  • <ProxyMatch>
  • ProxyMaxForwards
  • ProxyPass
  • ProxyPassInherit
  • ProxyPassInterpolateEnv
  • ProxyPassMatch
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • ProxyPreserveHost
  • ProxyReceiveBufferSize
  • ProxyRemote
  • ProxyRemoteMatch
  • ProxyRequests
  • ProxySCGIInternalRedirect
  • ProxySCGISendfile
  • ProxySet
  • ProxySourceAddress
  • ProxyStatus
  • ProxyTimeout
  • ProxyVia
  • QualifyRedirectURL
  • ReadmeName
  • ReceiveBufferSize
  • Redirect
  • RedirectMatch
  • RedirectPermanent
  • RedirectTemp
  • ReflectorHeader
  • RemoteIPHeader
  • RemoteIPInternalProxy
  • RemoteIPInternalProxyList
  • RemoteIPProxiesHeader
  • RemoteIPTrustedProxy
  • RemoteIPTrustedProxyList
  • RemoveCharset
  • RemoveEncoding
  • RemoveHandler
  • RemoveInputFilter
  • RemoveLanguage
  • RemoveOutputFilter
  • RemoveType
  • RequestHeader
  • RequestReadTimeout
  • Require
  • <RequireAll>
  • <RequireAny>
  • <RequireNone>
  • RewriteBase
  • RewriteCond
  • RewriteEngine
  • RewriteMap
  • RewriteOptions
  • RewriteRule
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • Satisfy
  • ScoreBoardFile
  • Script
  • ScriptAlias
  • ScriptAliasMatch
  • ScriptInterpreterSource
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength
  • ScriptSock
  • SecureListen
  • SeeRequestTail
  • SendBufferSize
  • ServerAdmin
  • ServerAlias
  • ServerLimit
  • ServerName
  • ServerPath
  • ServerRoot
  • ServerSignature
  • ServerTokens
  • Session
  • SessionCookieName
  • SessionCookieName2
  • SessionCookieRemove
  • SessionCryptoCipher
  • SessionCryptoDriver
  • SessionCryptoPassphrase
  • SessionCryptoPassphraseFile
  • SessionDBDCookieName
  • SessionDBDCookieName2
  • SessionDBDCookieRemove
  • SessionDBDDeleteLabel
  • SessionDBDInsertLabel
  • SessionDBDPerUser
  • SessionDBDSelectLabel
  • SessionDBDUpdateLabel
  • SessionEnv
  • SessionExclude
  • SessionHeader
  • SessionInclude
  • SessionMaxAge
  • SetEnv
  • SetEnvIf
  • SetEnvIfExpr
  • SetEnvIfNoCase
  • SetHandler
  • SetInputFilter
  • SetOutputFilter
  • SSIEndTag
  • SSIErrorMsg
  • SSIETag
  • SSILastModified
  • SSILegacyExprParser
  • SSIStartTag
  • SSITimeFormat
  • SSIUndefinedEcho
  • SSLCACertificateFile
  • SSLCACertificatePath
  • SSLCADNRequestFile
  • SSLCADNRequestPath
  • SSLCARevocationCheck
  • SSLCARevocationFile
  • SSLCARevocationPath
  • SSLCertificateChainFile
  • SSLCertificateFile
  • SSLCertificateKeyFile
  • SSLCipherSuite
  • SSLCompression
  • SSLCryptoDevice
  • SSLEngine
  • SSLFIPS
  • SSLHonorCipherOrder
  • SSLInsecureRenegotiation
  • SSLOCSPDefaultResponder
  • SSLOCSPEnable
  • SSLOCSPOverrideResponder
  • SSLOCSPProxyURL
  • SSLOCSPResponderTimeout
  • SSLOCSPResponseMaxAge
  • SSLOCSPResponseTimeSkew
  • SSLOCSPUseRequestNonce
  • SSLOpenSSLConfCmd
  • SSLOptions
  • SSLPassPhraseDialog
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
  • SSLProxyCARevocationCheck
  • SSLProxyCARevocationFile
  • SSLProxyCARevocationPath
  • SSLProxyCheckPeerCN
  • SSLProxyCheckPeerExpire
  • SSLProxyCheckPeerName
  • SSLProxyCipherSuite
  • SSLProxyEngine
  • SSLProxyMachineCertificateChainFile
  • SSLProxyMachineCertificateFile
  • SSLProxyMachineCertificatePath
  • SSLProxyProtocol
  • SSLProxyVerify
  • SSLProxyVerifyDepth
  • SSLRandomSeed
  • SSLRenegBufferSize
  • SSLRequire
  • SSLRequireSSL
  • SSLSessionCache
  • SSLSessionCacheTimeout
  • SSLSessionTicketKeyFile
  • SSLSessionTickets
  • SSLSRPUnknownUserSeed
  • SSLSRPVerifierFile
  • SSLStaplingCache
  • SSLStaplingErrorCacheTimeout
  • SSLStaplingFakeTryLater
  • SSLStaplingForceURL
  • SSLStaplingResponderTimeout
  • SSLStaplingResponseMaxAge
  • SSLStaplingResponseTimeSkew
  • SSLStaplingReturnResponderErrors
  • SSLStaplingStandardCacheTimeout
  • SSLStrictSNIVHostCheck
  • SSLUserName
  • SSLUseStapling
  • SSLVerifyClient
  • SSLVerifyDepth
  • StartServers
  • StartThreads
  • Substitute
  • SubstituteInheritBefore
  • SubstituteMaxLineLength
  • Suexec
  • SuexecUserGroup
  • ThreadLimit
  • ThreadsPerChild
  • ThreadStackSize
  • TimeOut
  • TraceEnable
  • TransferLog
  • TypesConfig
  • UnDefine
  • UndefMacro
  • UnsetEnv
  • Use
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • User
  • UserDir
  • VHostCGIMode
  • VHostCGIPrivs
  • VHostGroup
  • VHostPrivs
  • VHostSecure
  • VHostUser
  • VirtualDocumentRoot
  • VirtualDocumentRootIP
  • <VirtualHost>
  • VirtualScriptAlias
  • VirtualScriptAliasIP
  • WatchdogInterval
  • XBitHack
  • xml2EncAlias
  • xml2EncDefault
  • xml2StartParse

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Hızlı Yönerge Kılavuzu - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4 > Modüller

Hızlı Yönerge Kılavuzu

Bu hızlı yönerge kılavuzunda Apache yapılandırma yönergelerinin kullanımı, öntanımlı değerleri, durumu ve bağlamı gösterilmiştir. Bunların her biri hakkında ayrıntılı bilgi almak için Yönerge Sözlüğüne bakınız.

İlk sütunda yönergenin ismi ve kullanımı belirtilmiştir. İkinci sütunda yönergenin varsa öntanımlı değeri gösterilmiştir. Eğer öntanımlı değer sütuna sığmayacak kadar uzunsa sığmayan kısmı kırpılıp yerine “+” imi konmuştur.

Aşağıda sağdaki gösterge tablolarına uygun olarak, üçüncü sütunda yönergenin kullanımına izin verilen bağlamlar, dördüncü sütunda ise yönergenin durumu gösterilmiştir.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | Q | R | S | T | U | V | W | X
s | sunucu geneli
k | sanal konak
d | dizin
h | .htaccess

Ç | Çekirdek
M | MPM
T | Temel
E | Eklenti
D | Deneysel
H | Harici
AcceptFilter protocol kabul_süzgeci |  | s | Ç
Bir protokolün dinleyici soketleri için en iyilemeleri ayarlar
AcceptPathInfo On|Off|Default | Default | skdh | Ç
Dosya isminden sonra belirtilen yol verisini kabul veya reddeder.
AccessFileName filename [filename] ... | .htaccess | sk | Ç
Dağıtık yapılandırma dosyasının ismi belirtilir.
Action action-type cgi-script [virtual] |  | skdh | T
Activates a CGI script for a particular handler or content-type
AddAlt metin dosya [dosya] ... |  | skdh | T
Dosyaya göre seçilen simgenin yerinde gösterilecek metni belirler.
AddAltByEncoding metin MIME-kodlaması [MIME-kodlaması] ... |  | skdh | T
Dosyanın MIME kodlamasına göre seçilen simgenin yerinde gösterilecek metni belirler.
AddAltByType metin MIME-türü [MIME-türü] ... |  | skdh | T
Dosyanın MIME türüne göre seçilen simgenin yerinde gösterilecek metni belirler.
AddCharset charset extension [extension] ... |  | skdh | T
Maps the given filename extensions to the specified content charset
AddDefaultCharset On|Off|karküm | Off | skdh | Ç
Bir yanıtın içerik türü text/plain veya text/html olduğunda eklenecek öntanımlı karakter kümesi parametresini belirler.
AddDescription metin dosya [dosya] ... |  | skdh | T
Bir dosya için gösterilecek açıklama belirtilir.
AddEncoding encoding extension [extension] ... |  | skdh | T
Maps the given filename extensions to the specified encoding type
AddHandler handler-name extension [extension] ... |  | skdh | T
Maps the filename extensions to the specified handler
AddIcon simge isim [isim] ... |  | skdh | T
Bir dosya için gösterilecek simgeyi dosya adına göre belirler.
AddIconByEncoding simge MIME-kodlaması [MIME-kodlaması] ... |  | skdh | T
Bir dosya için gösterilecek simgeyi dosyanın MIME kodlamasına göre belirler.
AddIconByType simge MIME-türü [MIME-türü] ... |  | skdh | T
Bir dosya için gösterilecek simgeyi dosyanın MIME türüne göre belirler.
AddInputFilter filter[;filter...] extension [extension] ... |  | skdh | T
Maps filename extensions to the filters that will process client requests
AddLanguage language-tag extension [extension] ... |  | skdh | T
Maps the given filename extension to the specified content language
AddModuleInfo module-name string |  | sk | E
Adds additional information to the module information displayed by the server-info handler
AddOutputFilter filter[;filter...] extension [extension] ... |  | skdh | T
Maps filename extensions to the filters that will process responses from the server
AddOutputFilterByType filter[;filter...] media-type [media-type] ... |  | skdh | T
assigns an output filter to a particular media-type
AddType media-type extension [extension] ... |  | skdh | T
Maps the given filename extensions onto the specified content type
Alias [URL-yolu] dosya-yolu | dizin-yolu |  | skd | T
URL’leri dosya sistemi konumlarıyla eşler.
AliasMatch "düzenli-ifade" "dosya-yolu|dizin-yolu" |  | sk | T
URL’leri dosya sistemi konumlarıyla düzenli ifadeleri kullanarak eşler.
Allow from all|host|env=[!]env-variable [host|env=[!]env-variable] ... |  | dh | E
Controls which hosts can access an area of the server
AllowCONNECT port[-port] [port[-port]] ... | 443 563 | sk | E
Ports that are allowed to CONNECT through the proxy
AllowEncodedSlashes On|Off|NoDecode | Off | sk | Ç
Kodlanmış dosya yolu ayracı içeren URL’lere izin verilip verilmeyeceğini belirler.
AllowMethods reset|HTTP-method [HTTP-method]... | reset | d | D
Restrict access to the listed HTTP methods
AllowOverride All|None|yönerge-türü [yönerge-türü] ... | None (2.3.9 ve sonr + | d | Ç
.htaccess dosyalarında bulunmasına izin verilen yönerge türleri belirtilir.
AllowOverrideList None|yönerge [yönerge-türü] ... | None | d | Ç
.htaccess dosyalarında izin verilecek yönergeler tek tek belirtilir
Anonymous user [user] ... |  | dh | E
Specifies userIDs that are allowed access without password verification
Anonymous_LogEmail On|Off | On | dh | E
Sets whether the password entered will be logged in the error log
Anonymous_MustGiveEmail On|Off | On | dh | E
Specifies whether blank passwords are allowed
Anonymous_NoUserID On|Off | Off | dh | E
Sets whether the userID field may be empty
Anonymous_VerifyEmail On|Off | Off | dh | E
Sets whether to check the password field for a correctly formatted email address
AsyncRequestWorkerFactor factor |  | s | M
Limit concurrent connections per process
AuthBasicAuthoritative On|Off | On | dh | T
Sets whether authorization and authentication are passed to lower level modules
AuthBasicFake off|username [password] |  | dh | T
Fake basic authentication using the given expressions for username and password
AuthBasicProvider provider-name [provider-name] ... | file | dh | T
Sets the authentication provider(s) for this location
AuthBasicUseDigestAlgorithm MD5|Off | Off | dh | T
Check passwords against the authentication providers as if Digest Authentication was in force instead of Basic Authentication.
AuthDBDUserPWQuery query |  | d | E
SQL query to look up a password for a user
AuthDBDUserRealmQuery query |  | d | E
SQL query to look up a password hash for a user and realm.
AuthDBMGroupFile file-path |  | dh | E
Sets the name of the database file containing the list of user groups for authorization
AuthDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Sets the type of database file that is used to store passwords
AuthDBMUserFile file-path |  | dh | E
Sets the name of a database file containing the list of users and passwords for authentication
AuthDigestAlgorithm MD5|MD5-sess | MD5 | dh | E
Selects the algorithm used to calculate the challenge and response hashes in digest authentication
AuthDigestDomain URI [URI] ... |  | dh | E
URIs that are in the same protection space for digest authentication
AuthDigestNonceLifetime seconds | 300 | dh | E
How long the server nonce is valid
AuthDigestProvider provider-name [provider-name] ... | file | dh | E
Sets the authentication provider(s) for this location
AuthDigestQop none|auth|auth-int [auth|auth-int] | auth | dh | E
Determines the quality-of-protection to use in digest authentication
AuthDigestShmemSize size | 1000 | s | E
The amount of shared memory to allocate for keeping track of clients
AuthFormAuthoritative On|Off | On | dh | T
Sets whether authorization and authentication are passed to lower level modules
AuthFormBody fieldname |  | d | T
The name of a form field carrying the body of the request to attempt on successful login
AuthFormDisableNoStore On|Off | Off | d | T
Disable the CacheControl no-store header on the login page
AuthFormFakeBasicAuth On|Off | Off | d | T
Fake a Basic Authentication header
AuthFormLocation fieldname |  | d | T
The name of a form field carrying a URL to redirect to on successful login
AuthFormLoginRequiredLocation url |  | d | T
The URL of the page to be redirected to should login be required
AuthFormLoginSuccessLocation url |  | d | T
The URL of the page to be redirected to should login be successful
AuthFormLogoutLocation uri |  | d | T
The URL to redirect to after a user has logged out
AuthFormMethod fieldname |  | d | T
The name of a form field carrying the method of the request to attempt on successful login
AuthFormMimetype fieldname |  | d | T
The name of a form field carrying the mimetype of the body of the request to attempt on successful login
AuthFormPassword fieldname |  | d | T
The name of a form field carrying the login password
AuthFormProvider provider-name [provider-name] ... | file | dh | T
Sets the authentication provider(s) for this location
AuthFormSitePassphrase secret |  | d | T
Bypass authentication checks for high traffic sites
AuthFormSize size |  | d | T
The largest size of the form in bytes that will be parsed for the login details
AuthFormUsername fieldname |  | d | T
The name of a form field carrying the login username
AuthGroupFile file-path |  | dh | T
Sets the name of a text file containing the list of user groups for authorization
AuthLDAPAuthorizePrefix prefix | AUTHORIZE_ | dh | E
Specifies the prefix for environment variables set during authorization
AuthLDAPBindAuthoritative off|on | on | dh | E
Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
AuthLDAPBindDN distinguished-name |  | dh | E
Optional DN to use in binding to the LDAP server
AuthLDAPBindPassword password |  | dh | E
Password used in conjuction with the bind DN
AuthLDAPCharsetConfig file-path |  | s | E
Language to charset conversion configuration file
AuthLDAPCompareAsUser on|off | off | dh | E
Use the authenticated user's credentials to perform authorization comparisons
AuthLDAPCompareDNOnServer on|off | on | dh | E
Use the LDAP server to compare the DNs
AuthLDAPDereferenceAliases never|searching|finding|always | always | dh | E
When will the module de-reference aliases
AuthLDAPGroupAttribute attribute | member uniquemember + | dh | E
LDAP attributes used to identify the user members of groups.
AuthLDAPGroupAttributeIsDN on|off | on | dh | E
Use the DN of the client username when checking for group membership
AuthLDAPInitialBindAsUser off|on | off | dh | E
Determines if the server does the initial DN lookup using the basic authentication users' own username, instead of anonymously or with hard-coded credentials for the server
AuthLDAPInitialBindPattern regex substitution | (.*) $1 (remote use + | dh | E
Specifies the transformation of the basic authentication username to be used when binding to the LDAP server to perform a DN lookup
AuthLDAPMaxSubGroupDepth Number | 10 | dh | E
Specifies the maximum sub-group nesting depth that will be evaluated before the user search is discontinued.
AuthLDAPRemoteUserAttribute uid |  | dh | E
Use the value of the attribute returned during the user query to set the REMOTE_USER environment variable
AuthLDAPRemoteUserIsDN on|off | off | dh | E
Use the DN of the client username to set the REMOTE_USER environment variable
AuthLDAPSearchAsUser on|off | off | dh | E
Use the authenticated user's credentials to perform authorization searches
AuthLDAPSubGroupAttribute attribute |  | dh | E
Specifies the attribute labels, one value per directive line, used to distinguish the members of the current group that are groups.
AuthLDAPSubGroupClass LdapObjectClass | groupOfNames groupO + | dh | E
Specifies which LDAP objectClass values identify directory objects that are groups during sub-group processing.
AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS] |  | dh | E
URL specifying the LDAP search parameters
AuthMerging Off | And | Or | Off | dh | T
Controls the manner in which each configuration section's authorization logic is combined with that of preceding configuration sections.
AuthName auth-domain |  | dh | T
Authorization realm for use in HTTP authentication
AuthnCacheContext directory|server|custom-string |  | d | T
Specify a context string for use in the cache key
AuthnCacheEnable |  | s | T
Enable Authn caching configured anywhere
AuthnCacheProvideFor authn-provider [...] |  | dh | T
Specify which authn provider(s) to cache for
AuthnCacheSOCache provider-name[:provider-args] |  | s | T
Select socache backend provider to use
AuthnCacheTimeout timeout (seconds) |  | dh | T
Set a timeout for cache entries
<AuthnProviderAlias baseProvider Alias> ... </AuthnProviderAlias> |  | s | T
Enclose a group of directives that represent an extension of a base authentication provider and referenced by the specified alias
AuthnzFcgiCheckAuthnProvider provider-name|None option ... |  | d | E
Enables a FastCGI application to handle the check_authn authentication hook.
AuthnzFcgiDefineProvider type provider-name backend-address |  | s | E
Defines a FastCGI application as a provider for authentication and/or authorization
AuthType None|Basic|Digest|Form |  | dh | T
Type of user authentication
AuthUserFile file-path |  | dh | T
Sets the name of a text file containing the list of users and passwords for authentication
AuthzDBDLoginToReferer On|Off | Off | d | E
Determines whether to redirect the Client to the Referring page on successful login or logout if a Referer request header is present
AuthzDBDQuery query |  | d | E
Specify the SQL Query for the required operation
AuthzDBDRedirectQuery query |  | d | E
Specify a query to look up a login page for the user
AuthzDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Sets the type of database file that is used to store list of user groups
<AuthzProviderAlias baseProvider Alias Require-Parameters> ... </AuthzProviderAlias> |  | s | T
Enclose a group of directives that represent an extension of a base authorization provider and referenced by the specified alias
AuthzSendForbiddenOnFailure On|Off | Off | dh | T
Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if authentication succeeds but authorization fails
BalancerGrowth # | 5 | sk | E
Number of additional Balancers that can be added Post-configuration
BalancerInherit On|Off | On | sk | E
Inherit ProxyPassed Balancers/Workers from the main server
BalancerMember [balancerurl] url [key=value [key=value ...]] |  | d | E
Add a member to a load balancing group
BalancerPersist On|Off | Off | sk | E
Attempt to persist changes made by the Balancer Manager across restarts.
BrowserMatch düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ... |  | skdh | T
Ortam değişkenlerini HTTP kullanıcı arayüzüne göre belirler.
BrowserMatchNoCase düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ... |  | skdh | T
Ortam değişkenlerini HTTP kullanıcı arayüzünün harf büyüklüğüne duyarsız eşleşmelerine bağlı olarak belirler.
BufferedLogs On|Off | Off | s | T
Günlük girdilerini diske yazmadan önce bellekte tamponlar
BufferSize integer | 131072 | skdh | E
Maximum size in bytes to buffer by the buffer filter
CacheDefaultExpire seconds | 3600 (one hour) | skdh | E
The default duration to cache a document when no expiry date is specified.
CacheDetailHeader on|off | off | skdh | E
Add an X-Cache-Detail header to the response.
CacheDirLength length | 2 | sk | E
The number of characters in subdirectory names
CacheDirLevels levels | 2 | sk | E
The number of levels of subdirectories in the cache.
CacheDisable url-string | on |  | skdh | E
Disable caching of specified URLs
CacheEnable cache_type [url-string] |  | skd | E
Enable caching of specified URLs using a specified storage manager
CacheFile file-path [file-path] ... |  | s | D
Cache a list of file handles at startup time
CacheHeader on|off | off | skdh | E
Add an X-Cache header to the response.
CacheIgnoreCacheControl On|Off | Off | sk | E
Ignore request to not serve cached content to client
CacheIgnoreHeaders header-string [header-string] ... | None | sk | E
Do not store the given HTTP header(s) in the cache.
CacheIgnoreNoLastMod On|Off | Off | skdh | E
Ignore the fact that a response has no Last Modified header.
CacheIgnoreQueryString On|Off | Off | sk | E
Ignore query string when caching
CacheIgnoreURLSessionIdentifiers identifier [identifier] ... | None | sk | E
Ignore defined session identifiers encoded in the URL when caching
CacheKeyBaseURL URL | http://example.com | sk | E
Override the base URL of reverse proxied cache keys.
CacheLastModifiedFactor float | 0.1 | skdh | E
The factor used to compute an expiry date based on the LastModified date.
CacheLock on|off | off | sk | E
Enable the thundering herd lock.
CacheLockMaxAge integer | 5 | sk | E
Set the maximum possible age of a cache lock.
CacheLockPath directory | /tmp/mod_cache-lock + | sk | E
Set the lock path directory.
CacheMaxExpire seconds | 86400 (one day) | skdh | E
The maximum time in seconds to cache a document
CacheMaxFileSize bytes | 1000000 | skdh | E
The maximum size (in bytes) of a document to be placed in the cache
CacheMinExpire seconds | 0 | skdh | E
The minimum time in seconds to cache a document
CacheMinFileSize bytes | 1 | skdh | E
The minimum size (in bytes) of a document to be placed in the cache
CacheNegotiatedDocs On|Off | Off | sk | T
Allows content-negotiated documents to be cached by proxy servers
CacheQuickHandler on|off | on | sk | E
Run the cache from the quick handler.
CacheReadSize bytes | 0 | skdh | E
The minimum size (in bytes) of the document to read and be cached before sending the data downstream
CacheReadTime milliseconds | 0 | skdh | E
The minimum time (in milliseconds) that should elapse while reading before data is sent downstream
CacheRoot directory |  | sk | E
The directory root under which cache files are stored
CacheSocache type[:args] |  | sk | E
The shared object cache implementation to use
CacheSocacheMaxSize bytes | 102400 | skdh | E
The maximum size (in bytes) of an entry to be placed in the cache
CacheSocacheMaxTime seconds | 86400 | skdh | E
The maximum time (in seconds) for a document to be placed in the cache
CacheSocacheMinTime seconds | 600 | skdh | E
The minimum time (in seconds) for a document to be placed in the cache
CacheSocacheReadSize bytes | 0 | skdh | E
The minimum size (in bytes) of the document to read and be cached before sending the data downstream
CacheSocacheReadTime milliseconds | 0 | skdh | E
The minimum time (in milliseconds) that should elapse while reading before data is sent downstream
CacheStaleOnError on|off | on | skdh | E
Serve stale content in place of 5xx responses.
CacheStoreExpired On|Off | Off | skdh | E
Attempt to cache responses that the server reports as expired
CacheStoreNoStore On|Off | Off | skdh | E
Attempt to cache requests or responses that have been marked as no-store.
CacheStorePrivate On|Off | Off | skdh | E
Attempt to cache responses that the server has marked as private
CGIDScriptTimeout time[s|ms] |  | skdh | T
The length of time to wait for more output from the CGI program
CGIMapExtension cgi-yolu .uzantı |  | dh | Ç
CGI betik yorumlayıcısını saptama tekniğini belirler.
CGIPassAuth On|Off | Off | dh | Ç
HTTP yetkilendirme başlıklarının betiklere CGI değişkenleri olarak aktarılmasını etkin kılar
CharsetDefault charset |  | skdh | E
Charset to translate into
CharsetOptions option [option] ... | ImplicitAdd | skdh | E
Configures charset translation behavior
CharsetSourceEnc charset |  | skdh | E
Source charset of files
CheckCaseOnly on|off | Off | skdh | E
Limits the action of the speling module to case corrections
CheckSpelling on|off | Off | skdh | E
Enables the spelling module
ChrootDir /dizin/yolu |  | s | T
Sunucunun başlatıldıktan sonra chroot(8) yapacağı dizini belirler.
ContentDigest On|Off | Off | skdh | Ç
Content-MD5 HTTP yanıt başlıklarının üretimini etkin kılar.
CookieDomain domain |  | skdh | E
The domain to which the tracking cookie applies
CookieExpires expiry-period |  | skdh | E
Expiry time for the tracking cookie
CookieName token | Apache | skdh | E
Name of the tracking cookie
CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965 | Netscape | skdh | E
Format of the cookie header field
CookieTracking on|off | off | skdh | E
Enables tracking cookie
CoreDumpDirectory dizin |  | s | M
core dosyasını dökümlemek üzere Apache HTTP Sunucusunun geçmeye çalışacağı dizin.
CustomLog dosya|borulu-süreç biçem|takma-ad [env=[!]ortam-değişkeni]| expr=ifade] |  | sk | T
Günlük dosyasın ismini ve girdi biçemini belirler.
Dav On|Off|provider-name | Off | d | E
Enable WebDAV HTTP methods
DavDepthInfinity on|off | off | skd | E
Allow PROPFIND, Depth: Infinity requests
DavGenericLockDB file-path |  | skd | E
Location of the DAV lock database
DavLockDB file-path |  | sk | E
Location of the DAV lock database
DavMinTimeout seconds | 0 | skd | E
Minimum amount of time the server holds a lock on a DAV resource
DBDExptime time-in-seconds | 300 | sk | E
Keepalive time for idle connections
DBDInitSQL "SQL statement" |  | sk | E
Execute an SQL statement after connecting to a database
DBDKeep number | 2 | sk | E
Maximum sustained number of connections
DBDMax number | 10 | sk | E
Maximum number of connections
DBDMin number | 1 | sk | E
Minimum number of connections
DBDParams param1=value1[,param2=value2] |  | sk | E
Parameters for database connection
DBDPersist On|Off |  | sk | E
Whether to use persistent connections
DBDPrepareSQL "SQL statement" label |  | sk | E
Define an SQL prepared statement
DBDriver name |  | sk | E
Specify an SQL driver
DefaultIcon URL-yolu |  | skdh | T
Özel bir simge atanmamış dosyalar için gösterilecek simgeyi belirler.
DefaultLanguage language-tag |  | skdh | T
Defines a default language-tag to be sent in the Content-Language header field for all resources in the current context that have not been assigned a language-tag by some other means.
DefaultRuntimeDir dizin-yolu | DEFAULT_REL_RUNTIME + | s | Ç
Sunucunun çalışma anı dosyaları için temel dizin
DefaultType ortam-türü|none | none | skdh | Ç
Değeri none olduğu takdirde, bu yönergenin bir uyarı vermekten başka bir etkisi yoktur. Önceki sürümlerde, bu yönerge, sunucunun ortam türünü saptayamadığı durumda göndereceği öntanımlı ortam türünü belirlerdi.
Define değişken-ismi [değişken-değeri] |  | skd | Ç
Bir değişken tanımlar
DeflateBufferSize value | 8096 | sk | E
Fragment size to be compressed at one time by zlib
DeflateCompressionLevel value |  | sk | E
How much compression do we apply to the output
DeflateFilterNote [type] notename |  | sk | E
Places the compression ratio in a note for logging
DeflateInflateLimitRequestBodyvalue |  | skdh | E
Maximum size of inflated request bodies
DeflateInflateRatioBurst value |  | skdh | E
Maximum number of times the inflation ratio for request bodies can be crossed
DeflateInflateRatioLimit value |  | skdh | E
Maximum inflation ratio for request bodies
DeflateMemLevel value | 9 | sk | E
How much memory should be used by zlib for compression
DeflateWindowSize value | 15 | sk | E
Zlib compression window size
Deny from all|host|env=[!]env-variable [host|env=[!]env-variable] ... |  | dh | E
Controls which hosts are denied access to the server
<Directory "dizin-yolu"> ... </Directory> |  | sk | Ç
Sadece ismi belirtilen dosya sistemi dizininde ve bunun altdizinlerinde ve bunların içeriğinde uygulanacak bir yönerge grubunu sarmalar.
DirectoryCheckHandler On|Off | Off | skdh | T
Başka bir eylemci yapılandırılmışsa bu modülün nasıl yanıt vereceğini belirler
DirectoryIndex disabled | yerel-url [yerel-url] ... | index.html | skdh | T
İstemci bir dizin istediğinde dizin içeriğini listeler.
DirectoryIndexRedirect on | off | permanent | temp | seeother | 3xx-kodu | off | skdh | T
Dizin içerik listeleri için harici bir yönlendirme yapılandırır.
<DirectoryMatch düzifd> ... </DirectoryMatch> |  | sk | Ç
Bir düzenli ifade ile eşleşen dosya sistemi dizinlerinin içeriklerine uygulanacak bir yönerge grubunu sarmalar.
DirectorySlash On|Off | On | skdh | T
Bölü çizgisi ile biten yönlendirmeleri açar/kapar.
DocumentRoot dizin-yolu | "/usr/local/apache/ + | sk | Ç
İstemciye görünür olan ana belge ağacının kök dizinini belirler.
DTracePrivileges On|Off | Off | s | D
Determines whether the privileges required by dtrace are enabled.
DumpIOInput On|Off | Off | s | E
Dump all input data to the error log
DumpIOOutput On|Off | Off | s | E
Dump all output data to the error log
<Else> ... </Else> |  | skdh | Ç
Önceki bir <If> veya <ElseIf> bölümünün koşulu, çalışma anında bir istek tarafından yerine getirilmediği takdirde uygulanacak yönergeleri içerir
<ElseIf ifade> ... </ElseIf> |  | skdh | Ç
İçerdiği koşulun bir istek tarafınan sağlandığı ancak daha önceki bir <If> veya <ElseIf> bölümlerininkilerin sağlanmadığı durumda kapsadığı yönergelerin uygulanmasını sağlar
EnableExceptionHook On|Off | Off | s | M
Bir çöküş sonrası olağandışılık eylemcilerini çalıştıracak kancayı etkin kılar.
EnableMMAP On|Off | On | skdh | Ç
Teslimat sırasında okunacak dosyalar için bellek eşlemeyi etkin kılar.
EnableSendfile On|Off | Off | skdh | Ç
Dosyaların istemciye tesliminde çekirdeğin dosya gönderme desteğinin kullanımını etkin kılar.
Error ileti |  | skdh | Ç
Özel bir hata iletisiyle yapılandırma çözümlemesini durdurur
ErrorDocument hata-kodu belge |  | skdh | Ç
Bir hata durumunda sunucunun istemciye ne döndüreceğini belirler.
ErrorLog dosya-yolu|syslog[:oluşum] | logs/error_log (Uni + | sk | Ç
Sunucunun hata günlüğünü tutacağı yeri belirler.
ErrorLogFormat [connection|request] biçem |  | sk | Ç
Hata günlüğü girdileri için biçem belirtimi
Example |  | skdh | D
Demonstration directive to illustrate the Apache module API
ExpiresActive On|Off | Off | skdh | E
Enables generation of Expires headers
ExpiresByType MIME-type <code>seconds |  | skdh | E
Value of the Expires header configured by MIME type
ExpiresDefault <code>seconds |  | skdh | E
Default algorithm for calculating expiration time
ExtendedStatus On|Off | Off[*] | s | Ç
Her istekte ek durum bilgisinin izini sürer
ExtFilterDefine filtername parameters |  | s | E
Define an external filter
ExtFilterOptions option [option] ... | NoLogStderr | d | E
Configure mod_ext_filter options
FallbackResource disabled | yerel-url |  | skdh | T
Bir dosya ile eşleşmeyen istekler için öntanımlı URL tanımlar
FileETag bileşen ... | MTime Size | skdh | Ç
Duruk dosyalar için ETag HTTP yanıt başlığını oluşturmakta kullanılacak dosya özniteliklerini belirler.
<Files "dosya-adı"> ... </Files> |  | skdh | Ç
Dosya isimleriyle eşleşme halinde uygulanacak yönergeleri içerir.
<FilesMatch düzifd> ... </FilesMatch> |  | skdh | Ç
Düzenli ifadelerin dosya isimleriyle eşleşmesi halinde uygulanacak yönergeleri içerir.
FilterChain [+=-@!]filter-name ... |  | skdh | T
Configure the filter chain
FilterDeclare filter-name [type] |  | skdh | T
Declare a smart filter
FilterProtocol filter-name [provider-name] proto-flags |  | skdh | T
Deal with correct HTTP protocol handling
FilterProvider filter-name provider-name expression |  | skdh | T
Register a content filter
FilterTrace filter-name level |  | skd | T
Get debug/diagnostic information from mod_filter
ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] | Prefer | skdh | T
Action to take if a single acceptable document is not found
ForceType ortam-türü|None |  | dh | Ç
Bütün dosyaların belirtilen ortam türüyle sunulmasına sebep olur.
ForensicLog dosya-adı|borulu-süreç |  | sk | E
Adli günlük için dosya ismini belirler.
GlobalLog dosya|boru|sağlayıcı biçem|takma_ad [env=[!]ortam_değişkeni| expr=ifade] |  | s | T
Günlük dosyasının ismini ve biçemini belirler
GprofDir /tmp/gprof/|/tmp/gprof/% |  | sk | Ç
gmon.out ayrıntılı inceleme verisinin yazılacağı dizin
GracefulShutdownTimeout saniye | 0 | s | M
Sunucunun nazikçe kapatılmasının ardından ana süreç çıkana kadar geçecek süre için bir zaman aşımı belirler.
Group unix-grubu | #-1 | s | T
İsteklere yanıt verecek sunucunun ait olacağı grubu belirler.
H2Direct on|off | on for h2c, off for + | sk | E
H2 Direct Protocol Switch
H2KeepAliveTimeout seconds |  | sk | E
Timeout (in seconds) for idle HTTP/2 connections
H2MaxSessionStreams n | 100 | sk | E
Maximum number of active streams per HTTP/2 session.
H2MaxWorkerIdleSeconds n | 600 | s | E
Maximum number of seconds h2 workers remain idle until shut down.
H2MaxWorkers n |  | s | E
Maximum number of worker threads to use per child process.
H2MinWorkers n |  | s | E
Minimal number of worker threads to use per child process.
H2ModernTLSOnly on|off | on | sk | E
Require HTTP/2 connections to be "modern TLS" only
H2Push on|off | on | sk | E
H2 Server Push Switch
H2PushDiarySize n | 256 | sk | E
H2 Server Push Diary Size
H2PushPriority mime-type [after|before|interleaved] [weight] | * After 16 | sk | E
H2 Server Push Priority
H2SerializeHeaders on|off | off | sk | E
Serialize Request/Response Processing Switch
H2SessionExtraFiles n |  | sk | E
Number of Extra File Handles
H2StreamMaxMemSize bytes | 65536 | sk | E
Maximum amount of output data buffered per stream.
H2StreamTimeout seconds | 0 | sk | E
Timeout (in seconds) for idle HTTP/2 connections
H2Timeout seconds | 5 | sk | E
Timeout (in seconds) for HTTP/2 connections
H2TLSCoolDownSecs seconds | 1 | sk | E
-
H2TLSWarmUpSize amount | 1048576 | sk | E
-
H2Upgrade on|off | on for h2c, off for + | sk | E
H2 Upgrade Protocol Switch
H2WindowSize bytes | 65535 | sk | E
Size of Stream Window for upstream data.
Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]] |  | skdh | E
Configure HTTP response headers
HeaderName dosya-ismi |  | skdh | T
Dizin listesinin tepesine yerleştirilecek dosyanın ismini belirler.
HeartbeatAddress addr:port |  | s | D
Multicast address for heartbeat packets
HeartbeatListenaddr:port |  | s | D
multicast address to listen for incoming heartbeat requests
HeartbeatMaxServers number-of-servers | 10 | s | D
Specifies the maximum number of servers that will be sending heartbeat requests to this server
HeartbeatStorage file-path | logs/hb.dat | s | D
Path to store heartbeat data
HeartbeatStorage file-path | logs/hb.dat | s | D
Path to read heartbeat data
HostnameLookups On|Off|Double | Off | skd | Ç
İstemci IP adresleri üzerinde DNS sorgularını etkin kılar.
IdentityCheck On|Off | Off | skd | E
Enables logging of the RFC 1413 identity of the remote user
IdentityCheckTimeout seconds | 30 | skd | E
Determines the timeout duration for ident requests
<If ifade> ... </If> |  | skdh | Ç
Çalışma anında bir koşul bir istek tarafından yerine getirildiği takdirde uygulanacak yönergeleri barındırır.
<IfDefine [!]parametre-adı> ... </IfDefine> |  | skdh | Ç
Başlatma sırasında bir doğruluk sınamasından sonra işleme sokulacak yönergeleri sarmalar.
<IfModule [!]modül-dosyası|modül-betimleyici> ... </IfModule> |  | skdh | Ç
Belli bir modülün varlığına veya yokluğuna göre işleme sokulacak yönergeleri sarmalar.
<IfVersion [[!]operator] version> ... </IfVersion> |  | skdh | E
contains version dependent configuration
ImapBase map|referer|URL | http://servername/ | skdh | T
Default base for imagemap files
ImapDefault error|nocontent|map|referer|URL | nocontent | skdh | T
Default action when an imagemap is called with coordinates that are not explicitly mapped
ImapMenu none|formatted|semiformatted|unformatted | formatted | skdh | T
Action if no coordinates are given when calling an imagemap
Include dosya-yolu|dizin-yolu|joker |  | skd | Ç
Sunucu yapılandırma dosyalarının başka dosyaları içermesini sağlar.
IncludeOptional dosya-yolu|dizin-yolu|joker |  | skd | Ç
Diğer yapılandırma dosyalarının sunucu yapılandırma dosyasına dahil edilmesini sağlar
IndexHeadInsert "imlenim ..." |  | skdh | T
Bir dizin sayfasının HEAD bölümüne metin yerleştirir.
IndexIgnore dosya [dosya] ... | "." | skdh | T
Dizin içerik listesinden gizlenecek dosyaların listesi belirtilir.
IndexIgnoreReset ON|OFF |  | skdh | T
Bir dizini listelerken gizlenecek dosyalar listesini boşaltır
IndexOptions [+|-]seçenek [[+|-]seçenek] ... |  | skdh | T
Dizin içerik listesini yapılandıracak seçenekler belirtilir.
IndexOrderDefault Ascending|Descending Name|Date|Size|Description | Ascending Name | skdh | T
Dizin içerik listesinin öntanımlı sıralamasını belirler.
IndexStyleSheet url-yolu |  | skdh | T
Dizin listesine bir biçembent ekler.
InputSed sed-command |  | dh | D
Sed command to filter request data (typically POST data)
ISAPIAppendLogToErrors on|off | off | skdh | T
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
ISAPIAppendLogToQuery on|off | on | skdh | T
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
ISAPICacheFile file-path [file-path] ... |  | sk | T
ISAPI .dll files to be loaded at startup
ISAPIFakeAsync on|off | off | skdh | T
Fake asynchronous support for ISAPI callbacks
ISAPILogNotSupported on|off | off | skdh | T
Log unsupported feature requests from ISAPI extensions
ISAPIReadAheadBuffer size | 49152 | skdh | T
Size of the Read Ahead Buffer sent to ISAPI extensions
KeepAlive On|Off | On | sk | Ç
HTTP kalıcı bağlantılarını etkin kılar
KeepAliveTimeout sayı[ms] | 5 | sk | Ç
Bir kalıcı bağlantıda sunucunun bir sonraki isteği bekleme süresi
KeptBodySize azami_bayt_sayısı | 0 | d | T
mod_include gibi süzgeçler tarafından kullanılma olasılığına karşı istek gövdesi iptal edilmek yerine belirtilen azami boyutta tutulur.
LanguagePriority MIME-lang [MIME-lang] ... |  | skdh | T
The precendence of language variants for cases where the client does not express a preference
LDAPCacheEntries number | 1024 | s | E
Maximum number of entries in the primary LDAP cache
LDAPCacheTTL seconds | 600 | s | E
Time that cached items remain valid
LDAPConnectionPoolTTL n | -1 | sk | E
Discard backend connections that have been sitting in the connection pool too long
LDAPConnectionTimeout seconds |  | s | E
Specifies the socket connection timeout in seconds
LDAPLibraryDebug 7 |  | s | E
Enable debugging in the LDAP SDK
LDAPOpCacheEntries number | 1024 | s | E
Number of entries used to cache LDAP compare operations
LDAPOpCacheTTL seconds | 600 | s | E
Time that entries in the operation cache remain valid
LDAPReferralHopLimit number |  | dh | E
The maximum number of referral hops to chase before terminating an LDAP query.
LDAPReferrals On|Off|default | On | dh | E
Enable referral chasing during queries to the LDAP server.
LDAPRetries number-of-retries | 3 | s | E
Configures the number of LDAP server retries.
LDAPRetryDelay seconds | 0 | s | E
Configures the delay between LDAP server retries.
LDAPSharedCacheFile directory-path/filename |  | s | E
Sets the shared memory cache file
LDAPSharedCacheSize bytes | 500000 | s | E
Size in bytes of the shared-memory cache
LDAPTimeout seconds | 60 | s | E
Specifies the timeout for LDAP search and bind operations, in seconds
LDAPTrustedClientCert type directory-path/filename/nickname [password] |  | dh | E
Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates.
LDAPTrustedGlobalCert type directory-path/filename [password] |  | s | E
Sets the file or database containing global trusted Certificate Authority or global client certificates
LDAPTrustedMode type |  | sk | E
Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
LDAPVerifyServerCert On|Off | On | s | E
Force server certificate verification
<Limit yöntem [yöntem] ... > ... </Limit> |  | dh | Ç
Erişimi sınırlanacak HTTP yöntemleri için erişim sınırlayıcıları sarmalar.
<LimitExcept yöntem [yöntem] ... > ... </LimitExcept> |  | dh | Ç
İsimleri belirtilenler dışında kalan HTTP yöntemleri için kullanılacak erişim sınırlayıcıları sarmalar.
LimitInternalRecursion sayı [sayı] | 10 | sk | Ç
Dahili yönlendirmelerin ve istek içi isteklerin azami sayısını belirler.
LimitRequestBody bayt-sayısı | 0 | skdh | Ç
İstemci tarafından gönderilen HTTP istek gövdesinin toplam uzunluğunu sınırlar.
LimitRequestFields sayı | 100 | sk | Ç
İstemciden kabul edilecek HTTP isteği başlık alanlarının sayısını sınırlar.
LimitRequestFieldSize bayt-sayısı | 8190 | sk | Ç
İstemciden kabul edilecek HTTP isteği başlık uzunluğunu sınırlar.
LimitRequestLine bayt-sayısı | 8190 | sk | Ç
İstemciden kabul edilecek HTTP istek satırının uzunluğunu sınırlar.
LimitXMLRequestBody bayt-sayısı | 1000000 | skdh | Ç
Bir XML temelli istek gövdesinin uzunluğunu sınırlar.
Listen [IP-adresi:]port-numarası [protokol] |  | s | M
Sunucunun dinleyeceği IP adresini ve portu belirler.
ListenBacklog kuyruk-uzunluğu |  | s | M
Bekleyen bağlantılar kuyruğunun azami uzunluğunu belirler
ListenCoresBucketsRatio oran | 0 (iptal) | s | M
İşlemci çekirdek sayısının dinleyenlerin buket sayısına oranı
LoadFile dosya-ismi [dosya-ismi] ... |  | sk | E
Belirtilen nesne dosyasını veya kütüphaneyi sunucu ile ilintiler.
LoadModule modül dosya-ismi |  | sk | E
Belirtilen nesne dosyasını veya kütüphaneyi sunucu ile ilintiler ve etkin modül listesine ekler.
<Location "URL-yolu|URL"> ... </Location> |  | sk | Ç
İçerdiği yönergeler sadece eşleşen URL’lere uygulanır.
<LocationMatch düzifade> ... </LocationMatch> |  | sk | Ç
İçerdiği yönergeler sadece düzenli ifadelerle eşleşen URL’lere uygulanır.
LogFormat biçem|takma-ad [takma-ad] | "%h %l %u %t \"%r\" + | sk | T
Bir günlük dosyasında kullanılmak üzere girdi biçemi tanımlar.
LogIOTrackTTFB ON|OFF | OFF | skdh | E
İlk baytın yazılmasına kadar geçen süreyi izler
LogLevel [modül:]seviye [modül:seviye] ... | warn | skd | Ç
Hata günlüklerinin ayrıntı seviyesini belirler.
LogMessage message [hook=hook] [expr=expression] |  | d | D
Log user-defined message to error log
LuaAuthzProvider provider_name /path/to/lua/script.lua function_name |  | s | D
Plug an authorization provider function into mod_authz_core
LuaCodeCache stat|forever|never | stat | skdh | D
Configure the compiled code cache.
LuaHookAccessChecker /path/to/lua/script.lua hook_function_name [early|late] |  | skdh | D
Provide a hook for the access_checker phase of request processing
LuaHookAuthChecker /path/to/lua/script.lua hook_function_name [early|late] |  | skdh | D
Provide a hook for the auth_checker phase of request processing
LuaHookCheckUserID /path/to/lua/script.lua hook_function_name [early|late] |  | skdh | D
Provide a hook for the check_user_id phase of request processing
LuaHookFixups /path/to/lua/script.lua hook_function_name |  | skdh | D
Provide a hook for the fixups phase of a request processing
LuaHookInsertFilter /path/to/lua/script.lua hook_function_name |  | skdh | D
Provide a hook for the insert_filter phase of request processing
LuaHookLog /path/to/lua/script.lua log_function_name |  | skdh | D
Provide a hook for the access log phase of a request processing
LuaHookMapToStorage /path/to/lua/script.lua hook_function_name |  | skdh | D
Provide a hook for the map_to_storage phase of request processing
LuaHookTranslateName /path/to/lua/script.lua hook_function_name [early|late] |  | sk | D
Provide a hook for the translate name phase of request processing
LuaHookTypeChecker /path/to/lua/script.lua hook_function_name |  | skdh | D
Provide a hook for the type_checker phase of request processing
LuaInherit none|parent-first|parent-last | parent-first | skdh | D
Controls how parent configuration sections are merged into children
LuaInputFilter filter_name /path/to/lua/script.lua function_name |  | s | D
Provide a Lua function for content input filtering
LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name] |  | skdh | D
Map a path to a lua handler
LuaOutputFilter filter_name /path/to/lua/script.lua function_name |  | s | D
Provide a Lua function for content output filtering
LuaPackageCPath /path/to/include/?.soa |  | skdh | D
Add a directory to lua's package.cpath
LuaPackagePath /path/to/include/?.lua |  | skdh | D
Add a directory to lua's package.path
LuaQuickHandler /path/to/script.lua hook_function_name |  | sk | D
Provide a hook for the quick handler of request processing
LuaRoot /path/to/a/directory |  | skdh | D
Specify the base path for resolving relative paths for mod_lua directives
LuaScope once|request|conn|thread|server [min] [max] | once | skdh | D
One of once, request, conn, thread -- default is once
<Macro name [par1 .. parN]> ... </Macro> |  | skd | T
Define a configuration file macro
MaxConnectionsPerChild sayı | 0 | s | M
Tek bir çocuk sürecin ömrü boyunca işleme sokabileceği istek sayısını sınırlamakta kullanılır.
MaxKeepAliveRequests sayı | 100 | sk | Ç
Bir kalıcı bağlantıda izin verilen istek sayısı
MaxMemFree kB-sayısı | 2048 | s | M
free() çağrılmaksızın ana bellek ayırıcının ayırmasına izin verilen azami bellek miktarını belirler.
MaxRangeOverlaps default | unlimited | none | aralık-sayısı | 20 | skd | Ç
Özkaynağın tamamını döndürmeden önce izin verilen üst üste binen aralık sayısı (100-200,150-300 gibi)
MaxRangeReversals default | unlimited | none | aralık-sayısı | 20 | skd | Ç
Özkaynağın tamamını döndürmeden önce izin verilen ters sıralı aralık sayısı (100-200,50-70 gibi)
MaxRanges default | unlimited | none | aralık-sayısı | 200 | skd | Ç
Özkaynağın tamamını döndürmeden önce izin verilen aralık sayısı
MaxRequestWorkers sayı |  | s | M
Aynı anda işleme sokulacak azami bağlantı sayısı
MaxSpareServers sayı | 10 | s | M
Boştaki çocuk süreçlerin azami sayısı
MaxSpareThreads number |  | s | M
Boştaki azami evre sayısını belirler
MaxThreads number | 2048 | s | M
Set the maximum number of worker threads
MemcacheConnTTL num[units] | 15s | sk | E
Keepalive time for idle connections
MergeTrailers [on|off] | off | sk | Ç
Trailer alanlarının başlığa dahil edilip edilmeyeceğini belirler
MetaDir directory | .web | skdh | E
Name of the directory to find CERN-style meta information files
MetaFiles on|off | off | skdh | E
Activates CERN meta-file processing
MetaSuffix suffix | .meta | skdh | E
File name suffix for the file containing CERN-style meta information
MimeMagicFile file-path |  | sk | E
Enable MIME-type determination based on file contents using the specified magic file
MinSpareServers sayı | 5 | s | M
Boştaki çocuk süreçlerin asgari sayısı
MinSpareThreads sayı |  | s | M
İsteklerin ani artışında devreye girecek boştaki evrelerin asgari sayısını belirler.
MMapFile file-path [file-path] ... |  | s | D
Map a list of files into memory at startup time
ModemStandard V.21|V.26bis|V.32|V.34|V.92 |  | d | D
Modem standard to simulate
ModMimeUsePathInfo On|Off | Off | d | T
Tells mod_mime to treat path_info components as part of the filename
MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters] | NegotiatedOnly | skdh | T
The types of files that will be included when searching for a matching file with MultiViews
Mutex mekanizma [default|muteks-ismi] ... [OmitPID] | default | s | Ç
Muteks mekanizmasını ve kilit dosyası dizinini tüm muteksler veya belirtilenler için yapılandırır
NameVirtualHost adres[:port] |  | s | Ç
ÖNERİLMİYOR: İsme dayalı sanal konaklar için IP adresi belirtir
NoProxy host [host] ... |  | sk | E
Hosts, domains, or networks that will be connected to directly
NWSSLTrustedCerts filename [filename] ... |  | s | T
List of additional client certificates
NWSSLUpgradeable [IP-address:]portnumber |  | s | T
Allows a connection to be upgraded to an SSL connection upon request
Options [+|-]seçenek [[+|-]seçenek] ... | FollowSymlinks | skdh | Ç
Belli bir dizinde geçerli olacak özellikleri yapılandırır.
Order ordering | Deny,Allow | dh | E
Controls the default access state and the order in which Allow and Deny are evaluated.
OutputSed sed-command |  | dh | D
Sed command for filtering response content
PassEnv ortam-değişkeni [ortam-değişkeni] ... |  | skdh | T
Ortam değişkenlerini kabuktan aktarır.
PidFile dosya | logs/httpd.pid | s | M
Ana sürecin süreç kimliğinin (PID) kaydedileceği dosyayı belirler.
PrivilegesMode FAST|SECURE|SELECTIVE | FAST | skd | D
Trade off processing speed and efficiency vs security against malicious privileges-aware code.
Protocol protokol |  | sk | Ç
Dinlenen bir soket için protokol
ProtocolEcho On|Off | Off | sk | D
Turn the echo server on or off
Protocols protokol ... | http/1.1 | sk | Ç
Sunucu/sanal konak için kullanılabilecek protokoller
ProtocolsHonorOrder On|Off | On | sk | Ç
Uzlaşma sırasında protokollerin öncelik sırasını belirler
<Proxy wildcard-url> ...</Proxy> |  | sk | E
Container for directives applied to proxied resources
ProxyAddHeaders Off|On | On | skd | E
Add proxy information in X-Forwarded-* headers
ProxyBadHeader IsError|Ignore|StartBody | IsError | sk | E
Determines how to handle bad header lines in a response
ProxyBlock *|word|host|domain [word|host|domain] ... |  | sk | E
Words, hosts, or domains that are banned from being proxied
ProxyDomain Domain |  | sk | E
Default domain name for proxied requests
ProxyErrorOverride On|Off | Off | skd | E
Override error pages for proxied content
ProxyExpressDBMFile <pathname> |  | sk | E
Pathname to DBM file.
ProxyExpressDBMFile <type> |  | sk | E
DBM type of file.
ProxyExpressEnable [on|off] |  | sk | E
Enable the module functionality.
ProxyFtpDirCharset character set | ISO-8859-1 | skd | E
Define the character set for proxied FTP listings
ProxyFtpEscapeWildcards [on|off] |  | skd | E
Whether wildcards in requested filenames are escaped when sent to the FTP server
ProxyFtpListOnWildcard [on|off] |  | skd | E
Whether wildcards in requested filenames trigger a file listing
ProxyHTMLBufSize bytes |  | skd | T
Sets the buffer size increment for buffering inline scripts and stylesheets.
ProxyHTMLCharsetOut Charset | * |  | skd | T
Specify a charset for mod_proxy_html output.
ProxyHTMLDocType HTML|XHTML [Legacy] OR ProxyHTMLDocType fpi [SGML|XML] |  | skd | T
Sets an HTML or XHTML document type declaration.
ProxyHTMLEnable On|Off | Off | skd | T
Turns the proxy_html filter on or off.
ProxyHTMLEvents attribute [attribute ...] |  | skd | T
Specify attributes to treat as scripting events.
ProxyHTMLExtended On|Off | Off | skd | T
Determines whether to fix links in inline scripts, stylesheets, and scripting events.
ProxyHTMLFixups [lowercase] [dospath] [reset] |  | skd | T
Fixes for simple HTML errors.
ProxyHTMLInterp On|Off | Off | skd | T
Enables per-request interpolation of ProxyHTMLURLMap rules.
ProxyHTMLLinks element attribute [attribute2 ...] |  | skd | T
Specify HTML elements that have URL attributes to be rewritten.
ProxyHTMLMeta On|Off | Off | skd | T
Turns on or off extra pre-parsing of metadata in HTML <head> sections.
ProxyHTMLStripComments On|Off | Off | skd | T
Determines whether to strip HTML comments.
ProxyHTMLURLMap from-pattern to-pattern [flags] [cond] |  | skd | T
Defines a rule to rewrite HTML links
ProxyIOBufferSize bytes | 8192 | sk | E
Determine size of internal data throughput buffer
<ProxyMatch regex> ...</ProxyMatch> |  | sk | E
Container for directives applied to regular-expression-matched proxied resources
ProxyMaxForwards number | -1 | sk | E
Maximium number of proxies that a request can be forwarded through
ProxyPass [path] !|url [key=value [key=value ...]] [nocanon] [interpolate] [noquery] |  | skd | E
Maps remote servers into the local server URL-space
ProxyPassInherit On|Off | On | sk | E
Inherit ProxyPass directives defined from the main server
ProxyPassInterpolateEnv On|Off | Off | skd | E
Enable Environment Variable interpolation in Reverse Proxy configurations
ProxyPassMatch [regex] !|url [key=value [key=value ...]] |  | skd | E
Maps remote servers into the local server URL-space using regular expressions
ProxyPassReverse [path] url [interpolate] |  | skd | E
Adjusts the URL in HTTP response headers sent from a reverse proxied server
ProxyPassReverseCookieDomain internal-domain public-domain [interpolate] |  | skd | E
Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server
ProxyPassReverseCookiePath internal-path public-path [interpolate] |  | skd | E
Adjusts the Path string in Set-Cookie headers from a reverse- proxied server
ProxyPreserveHost On|Off | Off | skd | E
Use incoming Host HTTP request header for proxy request
ProxyReceiveBufferSize bytes | 0 | sk | E
Network buffer size for proxied HTTP and FTP connections
ProxyRemote match remote-server |  | sk | E
Remote proxy used to handle certain requests
ProxyRemoteMatch regex remote-server |  | sk | E
Remote proxy used to handle requests matched by regular expressions
ProxyRequests On|Off | Off | sk | E
Enables forward (standard) proxy requests
ProxySCGIInternalRedirect On|Off|Headername | On | skd | E
Enable or disable internal redirect responses from the backend
ProxySCGISendfile On|Off|Headername | Off | skd | E
Enable evaluation of X-Sendfile pseudo response header
ProxySet url key=value [key=value ...] |  | d | E
Set various Proxy balancer or member parameters
ProxySourceAddress address |  | sk | E
Set local IP address for outgoing proxy connections
ProxyStatus Off|On|Full | Off | sk | E
Show Proxy LoadBalancer status in mod_status
ProxyTimeout seconds |  | sk | E
Network timeout for proxied requests
ProxyVia On|Off|Full|Block | Off | sk | E
Information provided in the Via HTTP response header for proxied requests
QualifyRedirectURL ON|OFF | OFF | skd | Ç
REDIRECT_URL ortam değişkeninin tamamen nitelenmiş olup olmayacağını denetler
ReadmeName dosya-ismi |  | skdh | T
Dizin listesinin sonuna yerleştirilecek dosyanın ismini belirler.
ReceiveBufferSize bayt-sayısı | 0 | s | M
TCP alım tamponu boyu
Redirect [durum] [URL-yolu] URL |  | skdh | T
İstemciyi, bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
RedirectMatch [durum] düzenli-ifade URL |  | skdh | T
Geçerli URL ile eşleşen bir düzenli ifadeye dayanarak bir harici yönlendirme gönderir.
RedirectPermanent URL-yolu URL |  | skdh | T
İstemciyi, kalıcı bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
RedirectTemp URL-yolu URL |  | skdh | T
İstemciyi, geçici bir yönlendirme isteği döndürerek farklı bir URL’ye yönlendirir.
ReflectorHeader inputheader [outputheader] |  | skdh | T
Reflect an input header to the output headers
RemoteIPHeader header-field |  | sk | T
Declare the header field which should be parsed for useragent IP addresses
RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ... |  | sk | T
Declare client intranet IP addresses trusted to present the RemoteIPHeader value
RemoteIPInternalProxyList filename |  | sk | T
Declare client intranet IP addresses trusted to present the RemoteIPHeader value
RemoteIPProxiesHeader HeaderFieldName |  | sk | T
Declare the header field which will record all intermediate IP addresses
RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ... |  | sk | T
Declare client intranet IP addresses trusted to present the RemoteIPHeader value
RemoteIPTrustedProxyList filename |  | sk | T
Declare client intranet IP addresses trusted to present the RemoteIPHeader value
RemoveCharset extension [extension] ... |  | kdh | T
Removes any character set associations for a set of file extensions
RemoveEncoding extension [extension] ... |  | kdh | T
Removes any content encoding associations for a set of file extensions
RemoveHandler extension [extension] ... |  | kdh | T
Removes any handler associations for a set of file extensions
RemoveInputFilter extension [extension] ... |  | kdh | T
Removes any input filter associations for a set of file extensions
RemoveLanguage extension [extension] ... |  | kdh | T
Removes any language associations for a set of file extensions
RemoveOutputFilter extension [extension] ... |  | kdh | T
Removes any output filter associations for a set of file extensions
RemoveType extension [extension] ... |  | kdh | T
Removes any content type associations for a set of file extensions
RequestHeader add|append|edit|edit*|merge|set|setifempty|unset header [[expr=]value [replacement] [early|env=[!]varname|expr=expression]] |  | skdh | E
Configure HTTP request headers
RequestReadTimeout [header=timeout[-maxtimeout][,MinRate=rate] [body=timeout[-maxtimeout][,MinRate=rate] |  | sk | E
Set timeout values for receiving request headers and body from client.
Require [not] entity-name [entity-name] ... |  | dh | T
Tests whether an authenticated user is authorized by an authorization provider.
<RequireAll> ... </RequireAll> |  | dh | T
Enclose a group of authorization directives of which none must fail and at least one must succeed for the enclosing directive to succeed.
<RequireAny> ... </RequireAny> |  | dh | T
Enclose a group of authorization directives of which one must succeed for the enclosing directive to succeed.
<RequireNone> ... </RequireNone> |  | dh | T
Enclose a group of authorization directives of which none must succeed for the enclosing directive to not fail.
RewriteBase URL-path |  | dh | E
Sets the base URL for per-directory rewrites
RewriteCond TestString CondPattern |  | skdh | E
Defines a condition under which rewriting will take place
RewriteEngine on|off | off | skdh | E
Enables or disables runtime rewriting engine
RewriteMap MapName MapType:MapSource MapTypeOptions |  | sk | E
Defines a mapping function for key-lookup
RewriteOptions Options |  | skdh | E
Sets some special options for the rewrite engine
RewriteRule Pattern Substitution [flags] |  | skdh | E
Defines rules for the rewriting engine
RLimitCPU saniye|max [saniye|max] |  | skdh | Ç
Apache httpd alt süreçleri tarafından çalıştırılan süreçlerin işlemci tüketimine sınırlama getirir.
RLimitMEM bayt-sayısı|max [bayt-sayısı|max] |  | skdh | Ç
Apache httpd alt süreçleri tarafından çalıştırılan süreçlerin bellek tüketimine sınırlama getirir.
RLimitNPROC sayı|max [sayı|max] |  | skdh | Ç
Apache httpd alt süreçleri tarafından çalıştırılabilecek süreç sayısına sınırlama getirir.
Satisfy Any|All | All | dh | E
Interaction between host-level access control and user authentication
ScoreBoardFile dosya-yolu | logs/apache_runtime + | s | M
Çocuk süreçler için eşgüdüm verisini saklamakta kullanılan dosyanın yerini belirler.
Script method cgi-script |  | skd | T
Activates a CGI script for a particular request method.
ScriptAlias [URL-yolu] dosya-yolu|dizin-yolu |  | skd | T
Bir URL’yi dosya sistemindeki bir yere eşler ve hedefi bir CGI betiği olarak çalıştırır.
ScriptAliasMatch düzenli-ifade dosya-yolu|dizin-yolu |  | sk | T
Bir URL’yi dosya sistemindeki bir yere düzenli ifade kullanarak eşler ve hedefi bir CGI betiği olarak çalıştırır.
ScriptInterpreterSource Registry|Registry-Strict|Script | Script | skdh | Ç
CGI betikleri için yorumlayıcı belirleme tekniği
ScriptLog file-path |  | sk | T
Location of the CGI script error logfile
ScriptLogBuffer bytes | 1024 | sk | T
Maximum amount of PUT or POST requests that will be recorded in the scriptlog
ScriptLogLength bytes | 10385760 | sk | T
Size limit of the CGI script logfile
ScriptSock file-path | cgisock | s | T
The filename prefix of the socket to use for communication with the cgi daemon
SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL] |  | s | T
Enables SSL encryption for the specified port
SeeRequestTail On|Off | Off | s | Ç
İsteğin 63 karakterden büyük olduğu varsayımıyla, mod_status'un ilk 63 karakteri mi yoksa son 63 karakteri mi göstereceğini belirler.
SendBufferSize bayt-sayısı | 0 | s | M
TCP tamponu boyu
ServerAdmin eposta-adresi|URL |  | sk | Ç
Sunucunun hata iletilerinde istemciye göstereceği eposta adresi
ServerAlias konakadı [konakadı] ... |  | k | Ç
İstekleri isme dayalı sanal konaklarla eşleştirilirken kullanılacak konak adları için başka isimler belirtebilmeyi sağlar.
ServerLimit sayı |  | s | M
Ayarlanabilir süreç sayısının üst sınırını belirler.
ServerName [şema://]alan-adı|ip-adresi[:port] |  | sk | Ç
Sunucunun özdeşleşeceği konak ismi ve port.
ServerPath URL-yolu |  | k | Ç
Uyumsuz bir tarayıcı tarafından erişilmesi için bir isme dayalı sanal konak için meşru URL yolu
ServerRoot dizin-yolu | /usr/local/apache | s | Ç
Sunucu yapılandırması için kök dizin
ServerSignature On|Off|EMail | Off | skdh | Ç
Sunucu tarafından üretilen belgelerin dipnotunu ayarlar.
ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full | Full | s | Ç
Server HTTP yanıt başlığını yapılandırır.
Session On|Off | Off | skdh | E
Enables a session for the current directory or location
SessionCookieName name attributes |  | skdh | E
Name and attributes for the RFC2109 cookie storing the session
SessionCookieName2 name attributes |  | skdh | E
Name and attributes for the RFC2965 cookie storing the session
SessionCookieRemove On|Off | Off | skdh | E
Control for whether session cookies should be removed from incoming HTTP headers
SessionCryptoCipher name |  | skdh | D
The crypto cipher to be used to encrypt the session
SessionCryptoDriver name [param[=value]] |  | s | D
The crypto driver to be used to encrypt the session
SessionCryptoPassphrase secret [ secret ... ] |  | skdh | D
The key used to encrypt the session
SessionCryptoPassphraseFile filename |  | skd | D
File containing keys used to encrypt the session
SessionDBDCookieName name attributes |  | skdh | E
Name and attributes for the RFC2109 cookie storing the session ID
SessionDBDCookieName2 name attributes |  | skdh | E
Name and attributes for the RFC2965 cookie storing the session ID
SessionDBDCookieRemove On|Off | On | skdh | E
Control for whether session ID cookies should be removed from incoming HTTP headers
SessionDBDDeleteLabel label | deletesession | skdh | E
The SQL query to use to remove sessions from the database
SessionDBDInsertLabel label | insertsession | skdh | E
The SQL query to use to insert sessions into the database
SessionDBDPerUser On|Off | Off | skdh | E
Enable a per user session
SessionDBDSelectLabel label | selectsession | skdh | E
The SQL query to use to select sessions from the database
SessionDBDUpdateLabel label | updatesession | skdh | E
The SQL query to use to update existing sessions in the database
SessionEnv On|Off | Off | skdh | E
Control whether the contents of the session are written to the HTTP_SESSION environment variable
SessionExclude path |  | skdh | E
Define URL prefixes for which a session is ignored
SessionHeader header |  | skdh | E
Import session updates from a given HTTP response header
SessionInclude path |  | skdh | E
Define URL prefixes for which a session is valid
SessionMaxAge maxage | 0 | skdh | E
Define a maximum age in seconds for a session
SetEnv ortam-değişkeni [değer] |  | skdh | T
Ortam değişkenlerini tanımlar.
SetEnvIf öznitelik düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ... |  | skdh | T
Ortam değişkenlerini isteğin özniteliklerine göre atar.
SetEnvIfExpr ifade [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ... |  | skdh | T
Bir ap_expr ifadesine dayanarak ortam değişkenlerine değer atar
SetEnvIfNoCase öznitelik düzifd [!]ort-değişkeni[=değer] [[!]ort-değişkeni[=değer]] ... |  | skdh | T
Ortam değişkenlerini isteğin özniteliklerinde harf büyüklüğüne bağlı olmaksızın yapılmış tanımlara göre atar.
SetHandler eylemci-ismi|none|ifade |  | skdh | Ç
Eşleşen tüm dosyaların belli bir eylemci tarafından işlenmesine sebep olur.
SetInputFilter süzgeç[;süzgeç...] |  | skdh | Ç
POST girdilerini ve istemci isteklerini işleyecek süzgeçleri belirler.
SetOutputFilter süzgeç[;süzgeç...] |  | skdh | Ç
Sunucunun yanıtlarını işleyecek süzgeçleri belirler.
SSIEndTag tag | "-->" | sk | T
String that ends an include element
SSIErrorMsg message | "[an error occurred + | skdh | T
Error message displayed when there is an SSI error
SSIETag on|off | off | dh | T
Controls whether ETags are generated by the server.
SSILastModified on|off | off | dh | T
Controls whether Last-Modified headers are generated by the server.
SSILegacyExprParser on|off | off | dh | T
Enable compatibility mode for conditional expressions.
SSIStartTag tag | "<!--#" | sk | T
String that starts an include element
SSITimeFormat formatstring | "%A, %d-%b-%Y %H:%M + | skdh | T
Configures the format in which date strings are displayed
SSIUndefinedEcho string | "(none)" | skdh | T
String displayed when an unset variable is echoed
SSLCACertificateFile file-path |  | sk | E
File of concatenated PEM-encoded CA Certificates for Client Auth
SSLCACertificatePath directory-path |  | sk | E
Directory of PEM-encoded CA Certificates for Client Auth
SSLCADNRequestFile file-path |  | sk | E
File of concatenated PEM-encoded CA Certificates for defining acceptable CA names
SSLCADNRequestPath directory-path |  | sk | E
Directory of PEM-encoded CA Certificates for defining acceptable CA names
SSLCARevocationCheck chain|leaf|none | none | sk | E
Enable CRL-based revocation checking
SSLCARevocationFile file-path |  | sk | E
File of concatenated PEM-encoded CA CRLs for Client Auth
SSLCARevocationPath directory-path |  | sk | E
Directory of PEM-encoded CA CRLs for Client Auth
SSLCertificateChainFile file-path |  | sk | E
File of PEM-encoded Server CA Certificates
SSLCertificateFile file-path |  | sk | E
Server PEM-encoded X.509 certificate data file
SSLCertificateKeyFile file-path |  | sk | E
Server PEM-encoded private key file
SSLCipherSuite cipher-spec | DEFAULT (depends on + | skdh | E
Cipher Suite available for negotiation in SSL handshake
SSLCompression on|off | off | sk | E
Enable compression on the SSL level
SSLCryptoDevice engine | builtin | s | E
Enable use of a cryptographic hardware accelerator
SSLEngine on|off|optional | off | sk | E
SSL Engine Operation Switch
SSLFIPS on|off | off | s | E
SSL FIPS mode Switch
SSLHonorCipherOrder on|off | off | sk | E
Option to prefer the server's cipher preference order
SSLInsecureRenegotiation on|off | off | sk | E
Option to enable support for insecure renegotiation
SSLOCSDefaultResponder uri |  | sk | E
Set the default responder URI for OCSP validation
SSLOCSPEnable on|off | off | sk | E
Enable OCSP validation of the client certificate chain
SSLOCSPOverrideResponder on|off | off | sk | E
Force use of the default responder URI for OCSP validation
SSLOCSPProxyURL url |  | sk | E
Proxy URL to use for OCSP requests
SSLOCSPResponderTimeout seconds | 10 | sk | E
Timeout for OCSP queries
SSLOCSPResponseMaxAge seconds | -1 | sk | E
Maximum allowable age for OCSP responses
SSLOCSPResponseTimeSkew seconds | 300 | sk | E
Maximum allowable time skew for OCSP response validation
SSLOCSPUseRequestNonce on|off | on | sk | E
Use a nonce within OCSP queries
SSLOpenSSLConfCmd command-name command-value |  | sk | E
Configure OpenSSL parameters through its SSL_CONF API
SSLOptions [+|-]option ... |  | skdh | E
Configure various SSL engine run-time options
SSLPassPhraseDialog type | builtin | s | E
Type of pass phrase dialog for encrypted private keys
SSLProtocol [+|-]protocol ... | all -SSLv3 (up to 2 + | sk | E
Configure usable SSL/TLS protocol versions
SSLProxyCACertificateFile file-path |  | sk | E
File of concatenated PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCACertificatePath directory-path |  | sk | E
Directory of PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCARevocationCheck chain|leaf|none | none | sk | E
Enable CRL-based revocation checking for Remote Server Auth
SSLProxyCARevocationFile file-path |  | sk | E
File of concatenated PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCARevocationPath directory-path |  | sk | E
Directory of PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCheckPeerCN on|off | on | sk | E
Whether to check the remote server certificate's CN field
SSLProxyCheckPeerExpire on|off | on | sk | E
Whether to check if remote server certificate is expired
SSLProxyCheckPeerName on|off | on | sk | E
Configure host name checking for remote server certificates
SSLProxyCipherSuite cipher-spec | ALL:!ADH:RC4+RSA:+H + | skdh | E
Cipher Suite available for negotiation in SSL proxy handshake
SSLProxyEngine on|off | off | sk | E
SSL Proxy Engine Operation Switch
SSLProxyMachineCertificateChainFile filename |  | s | E
File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate
SSLProxyMachineCertificateFile filename |  | s | E
File of concatenated PEM-encoded client certificates and keys to be used by the proxy
SSLProxyMachineCertificatePath directory |  | s | E
Directory of PEM-encoded client certificates and keys to be used by the proxy
SSLProxyProtocol [+|-]protocol ... | all -SSLv3 (up to 2 + | sk | E
Configure usable SSL protocol flavors for proxy usage
SSLProxyVerify level | none | sk | E
Type of remote server Certificate verification
SSLProxyVerifyDepth number | 1 | sk | E
Maximum depth of CA Certificates in Remote Server Certificate verification
SSLRandomSeed context source [bytes] |  | s | E
Pseudo Random Number Generator (PRNG) seeding source
SSLRenegBufferSize bytes | 131072 | dh | E
Set the size for the SSL renegotiation buffer
SSLRequire expression |  | dh | E
Allow access only when an arbitrarily complex boolean expression is true
SSLRequireSSL |  | dh | E
Deny access when SSL is not used for the HTTP request
SSLSessionCache type | none | s | E
Type of the global/inter-process SSL Session Cache
SSLSessionCacheTimeout seconds | 300 | sk | E
Number of seconds before an SSL session expires in the Session Cache
SSLSessionTicketKeyFile file-path |  | sk | E
Persistent encryption/decryption key for TLS session tickets
SSLSessionTickets on|off | on | sk | E
Enable or disable use of TLS session tickets
SSLSRPUnknownUserSeed secret-string |  | sk | E
SRP unknown user seed
SSLSRPVerifierFile file-path |  | sk | E
Path to SRP verifier file
SSLStaplingCache type |  | s | E
Configures the OCSP stapling cache
SSLStaplingErrorCacheTimeout seconds | 600 | sk | E
Number of seconds before expiring invalid responses in the OCSP stapling cache
SSLStaplingFakeTryLater on|off | on | sk | E
Synthesize "tryLater" responses for failed OCSP stapling queries
SSLStaplingForceURL uri |  | sk | E
Override the OCSP responder URI specified in the certificate's AIA extension
SSLStaplingResponderTimeout seconds | 10 | sk | E
Timeout for OCSP stapling queries
SSLStaplingResponseMaxAge seconds | -1 | sk | E
Maximum allowable age for OCSP stapling responses
SSLStaplingResponseTimeSkew seconds | 300 | sk | E
Maximum allowable time skew for OCSP stapling response validation
SSLStaplingReturnResponderErrors on|off | on | sk | E
Pass stapling related OCSP errors on to client
SSLStaplingStandardCacheTimeout seconds | 3600 | sk | E
Number of seconds before expiring responses in the OCSP stapling cache
SSLStrictSNIVHostCheck on|off | off | sk | E
Whether to allow non-SNI clients to access a name-based virtual host.
SSLUserName varname |  | sdh | E
Variable name to determine user name
SSLUseStapling on|off | off | sk | E
Enable stapling of OCSP responses in the TLS handshake
SSLVerifyClient level | none | skdh | E
Type of Client Certificate verification
SSLVerifyDepth number | 1 | skdh | E
Maximum depth of CA Certificates in Client Certificate verification
StartServers sayı |  | s | M
Sunucunun başlatılması sırasında oluşturulan çocuk süreçlerin sayısını belirler.
StartThreads sayı |  | s | M
Sunucunun başlatılması sırasında oluşturulan evrelerin sayısını belirler.
Substitute s/pattern/substitution/[infq] |  | dh | E
Pattern to filter the response content
SubstituteInheritBefore on|off | off | dh | E
Change the merge order of inherited patterns
SubstituteMaxLineLength bytes(b|B|k|K|m|M|g|G) | 1m | dh | E
Set the maximum line size
Suexec On|Off |  | s | T
suEXEC özelliğini etkin veya etkisiz yapar
SuexecUserGroup Kullanıcı Grup |  | sk | E
CGI betiklerini çalıştıracak kullanıcı ve grup belirtilir.
ThreadLimit sayı |  | s | M
Çocuk süreç başına ayarlanabilir evre sayısının üst sınırını belirler.
ThreadsPerChild sayı |  | s | M
Her çocuk süreç tarafından oluşturulan evrelerin sayısını belirler.
ThreadStackSize boyut |  | s | M
İstemci bağlantılarını elde eden evreler tarafından kullanılan yığıtın bayt cinsinden uzunluğunu belirler.
TimeOut saniye | 60 | sk | Ç
Bir istek için başarısız olmadan önce belirli olayların gerçekleşmesi için sunucunun geçmesini bekleyeceği süre.
TraceEnable [on|off|extended] | on | sk | Ç
TRACE isteklerinde davranış şeklini belirler
TransferLog dosya|borulu-süreç [takma-ad] |  | sk | T
Bir günlük dosyasının yerini belirtir.
TypesConfig file-path | conf/mime.types | s | T
The location of the mime.types file
UnDefine değişken-ismi |  | s | Ç
Bir değişkeni tanımsız yapar
UndefMacro name |  | skd | T
Undefine a macro
UnsetEnv ortam-değişkeni [ortam-değişkeni] ... |  | skdh | T
Ortamdaki değişkenleri tanımsız hale getirir.
Use name [value1 ... valueN] |  | skd | T
Use a macro
UseCanonicalName On|Off|DNS | Off | skd | Ç
Sunucunun kendi adını ve portunu nasıl belirleyeceğini ayarlar
UseCanonicalPhysicalPort On|Off | Off | skd | Ç
Sunucunun kendi adını ve portunu nasıl belirleyeceğini ayarlar
User unix-kullanıcısı | #-1 | s | T
İsteklere yanıt verecek sunucunun ait olacağı kullanıcıyı belirler.
UserDir dizin [dizin] ... |  | sk | T
Kullanıcıya özel dizinlerin yeri
VHostCGIMode On|Off|Secure | On | k | D
Determines whether the virtualhost can run subprocesses, and the privileges available to subprocesses.
VHostPrivs [+-]?privilege-name [[+-]?privilege-name] ... |  | k | D
Assign arbitrary privileges to subprocesses created by a virtual host.
VHostGroup unix-groupid |  | k | D
Sets the Group ID under which a virtual host runs.
VHostPrivs [+-]?privilege-name [[+-]?privilege-name] ... |  | k | D
Assign arbitrary privileges to a virtual host.
VHostSecure On|Off | On | k | D
Determines whether the server runs with enhanced security for the virtualhost.
VHostUser unix-userid |  | k | D
Sets the User ID under which a virtual host runs.
VirtualDocumentRoot hesaplanan-dizin|none | none | sk | E
Bir sanal konağın belge kök dizinini devingen olarak yapılandırır.
VirtualDocumentRootIP hesaplanan-dizin|none | none | sk | E
Bir sanal konağın belge kök dizinini devingen olarak yapılandırır.
<VirtualHost adres[:port] [adres[:port]] ...> ... </VirtualHost> |  | s | Ç
Sadece belli bir konak ismine ve porta uygulanacak yönergeleri barındırır.
VirtualScriptAlias hesaplanan-dizin|none | none | sk | E
Bir sanal konağın CGI dizinini devingen olarak yapılandırır.
VirtualScriptAliasIP hesaplanan-dizin|none | none | sk | E
Bir sanal konağın CGI dizinini devingen olarak yapılandırır.
WatchdogInterval number-of-seconds | 1 | s | T
Watchdog interval in seconds
XBitHack on|off|full | off | skdh | T
Parse SSI directives in files with the execute bit set
xml2EncAlias charset alias [alias ...] |  | s | T
Recognise Aliases for encoding values
xml2EncDefault name |  | skdh | T
Sets a default encoding to assume when absolutely no information can be automatically detected
xml2StartParse element [element ...] |  | skdh | T
Advise the parser to skip leading junk.

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.


Getting Started - Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Getting Started

If you're completely new to the Apache HTTP Server, or even to running a website at all, you might not know where to start, or what questions to ask. This document walks you through the basics.

Clients, Servers, and URLs

Addresses on the Web are expressed with URLs - Uniform Resource Locators - which specify a protocol (e.g. http), a servername (e.g. www.apache.org), a URL-path (e.g. /docs/current/getting-started.html), and possibly a query string (e.g. ?arg=value) used to pass additional arguments to the server.

A client (e.g., a web browser) connects to a server (e.g., your Apache HTTP Server), with the specified protocol, and makes a request for a resource using the URL-path.

The URL-path may represent any number of things on the server. It may be a file (like getting-started.html) a handler (like server-status) or some kind of program file (like index.php). We'll discuss this more below in the Web Site Content section.

The server will send a response consisting of a status code and, optionally, a response body. The status code indicates whether the request was successful, and, if not, what kind of error condition there was. This tells the client what it should do with the response. You can read about the possible response codes in HTTP Server wiki.

Details of the transaction, and any error conditions, are written to log files. This is discussed in greater detail below in the Logs Files and Troubleshooting section.

Hostnames and DNS

In order to connect to a server, the client will first have to resolve the servername to an IP address - the location on the Internet where the server resides. Thus, in order for your web server to be reachable, it is necessary that the servername be in DNS.

If you don't know how to do this, you'll need to contact your network administrator, or Internet service provider, to perform this step for you.

More than one hostname may point to the same IP address, and more than one IP address can be attached to the same physical server. Thus, you can run more than one web site on the same physical server, using a feature called virtual hosts.

If you are testing a server that is not Internet-accessible, you can put host names in your hosts file in order to do local resolution. For example, you might want to put a record in your hosts file to map a request for www.example.com to your local system, for testing purposes. This entry would look like:

127.0.0.1 www.example.com

A hosts file will probably be located at /etc/hosts or C:\Windows\system32\drivers\etc\hosts.

You can read more about the hosts file at Wikipedia.org/wiki/Hosts_(file), and more about DNS at Wikipedia.org/wiki/Domain_Name_System.

Configuration Files and Directives

The Apache HTTP Server is configured via simple text files. These files may be located any of a variety of places, depending on how exactly you installed the server. Common locations for these files may be found in the httpd wiki. If you installed httpd from source, the default location of the configuration files is /usr/local/apache2/conf. The default configuration file is usually called httpd.conf. This, too, can vary in third-party distributions of the server.

The configuration is frequently broken into multiple smaller files, for ease of management. These files are loaded via the Include directive. The names or locations of these sub-files are not magical, and may vary greatly from one installation to another. Arrange and subdivide these files as makes the most sense to you. If the file arrangement you have by default doesn't make sense to you, feel free to rearrange it.

The server is configured by placing configuration directives in these configuration files. A directive is a keyword followed by one or more arguments that set its value.

The question of "Where should I put that directive?" is generally answered by considering where you want a directive to be effective. If it is a global setting, it should appear in the configuration file, outside of any <Directory>, <Location>, <VirtualHost>, or other section. If it is to apply only to a particular directory, then it should go inside a <Directory> section referring to that directory, and so on. See the Configuration Sections document for further discussion of these sections.

In addition to the main configuration files, certain directives may go in .htaccess files located in the content directories. .htaccess files are primarily for people who do not have access to the main server configuration file(s). You can read more about .htaccess files in the .htaccess howto.

Web Site Content

Web site content can take many different forms, but may be broadly divided into static and dynamic content.

Static content is things like HTML files, image files, CSS files, and other files that reside in the filesystem. The DocumentRoot directive specifies where in your filesystem you should place these files. This directive is either set globally, or per virtual host. Look in your configuration file(s) to determine how this is set for your server.

Typically, a document called index.html will be served when a directory is requested without a file name being specified. For example, if DocumentRoot is set to /var/www/html and a request is made for http://www.example.com/work/, the file /var/www/html/work/index.html will be served to the client.

Dynamic content is anything that is generated at request time, and may change from one request to another. There are numerous ways that dynamic content may be generated. Various handlers are available to generate content. CGI programs may be written to generate content for your site.

Third-party modules like mod_php may be used to write code that does a variety of things. Many third-party applications, written using a variety of languages and tools, are available for download and installation on your Apache HTTP Server. Support of these third-party things is beyond the scope of this documentation, and you should find their documentation or other support forums to answer your questions about them.

Log Files and Troubleshooting

As an Apache HTTP Server administrator, your most valuable assets are the log files, and, in particular, the error log. Troubleshooting any problem without the error log is like driving with your eyes closed.

The location of the error log is defined by the ErrorLog directive, which may be set globally, or per virtual host. Entries in the error log tell you what went wrong, and when. They often also tell you how to fix it. Each error log message contains an error code, which you can search for online for even more detailed descriptions of how to address the problem. You can also configure your error log to contain a log ID which you can then correlate to an access log entry, so that you can determine what request caused the error condition.

You can read more about logging in the logs documentation.

What's next?

Once you have the prerequisites under your belt, it's time to move on.

This document covers only the bare basics. We hope that this gets you started, but there are many other things that you might need to know.

  • Download
  • Install
  • Configure
  • Start
  • Frequently Asked Questions


Site Haritası - Apache HTTP Sunucusu Sürüm 2.4

Apache HTTP Sunucusu Sürüm 2.4

Apache > HTTP Sunucusu > Belgeleme > Sürüm 2.4

Site Haritası

Bu sayfada Apache HTTP Sunucusu Sürüm 2.4 Belgelerinin tamamı listelenmiştir.

Sürümlerin Dağıtım Bilgileri

  • 2.4’e 2.2’den yükseltme
  • 2.3/2.4’teki yeni özellikler
  • Apache 2.1/2.2’deki yeni özellikler
  • Apache 2.0’daki yeni özellikler
  • Apache Lisansı

Apache HTTP Sunucusunun Kullanımı

  • Derleme ve Kurulum
  • Sunucuyu Başlatma
  • Sunucuyu Durdurma ve Yeniden Başlatma
  • Yapılandırma Dosyaları
  • Directory, Location ve Files Bölümleri Nasıl Çalışır
  • İçerik Bellekleme
  • Sunucu Genelinde Yapılandırma
  • Günlük Dosyaları
  • URL’lerin Dosya Sistemi ile Eşlenmesi
  • Devingen Paylaşımlı Nesne (DSO) Desteği
  • İçerik Dili Uzlaşımı
  • Özel Hata Yanıtları
  • Sunucunun Kullandığı Adreslerin ve Portların Ayarlanması
  • Çok Süreçlilik Modülleri (MPM’ler)
  • Ortam Değişkenleri
  • Apache'de İfadelerin Çözümlenmesi
  • Eylemci Kullanımı
  • Süzgeçler
  • Paylaşımlı Nesne Arabelleği Desteği
  • CGI için Suexec Desteği
  • DNS ile ilgili Konular ve Apache
  • Sıkça Sorulan Sorular

Apache Sanal Konak (VirtualHost) Belgeleri

  • Genel Bakış
  • İsme göre Sanal Konak Desteği
  • IP Adresine göre Sanal Konak Desteği
  • Sanal Konakların Devingen olarak Yapılandırılması
  • VirtualHost Örnekleri
  • Sanal Konak Eşleştirmesinin Derinliğine İncelenmesi
  • Dosya Tanıtıcı Sınırlamaları

URL’lerin Yeniden Yazılması

  • Genel Bakış
  • mod_rewrite Başvuru Belgesi
  • mod_rewrite ve düzenli ifadelere giriş
  • URL'lerin yeniden eşlenmesi ve yönlendirilmesi içinmod_rewrite kullanımı
  • Erişim denetimi için mod_rewrite kullanımı
  • mod_rewrite ile devingen sanal konaklar
  • mod_rewrite ile devingen vekil kullanımı
  • RewriteMap kullanımı
  • İleri seviye teknikler
  • mod_rewrite ne zaman kullanılMAZ
  • RewriteRule Seçenekleri
  • Teknik Ayrıntılar

Apache SSL/TLS Şifrelemesi

  • Genel Bakış
  • SSL/TLS Şifrelemesi: Giriş
  • SSL/TLS Şifrelemesi: Uyumluluk
  • SSL/TLS Şifrelemesi: Nasıl
  • SSL/TLS Şifrelemesi: SSS

Kılavuzlar, Öğreticiler ve Nasıllar

  • Genel Bakış
  • Kimlik Doğrulama ve Yetkilendirme
  • Erişim Denetimi
  • CGI ile Devingen İçerik
  • Sunucu Taraflı İçerik Yerleştirme (SSI)
  • .htaccess Dosyaları
  • Kullanıcı Dizinleri (public_html)
  • Ters Vekil Yapılandırma Rehberi

Platformlara Özgü Bilgiler

  • Genel Bakış
  • Microsoft Windows ile Apache Kullanımı
  • Microsoft Windows için Apache Derleme
  • RPM Temelli Sistemlerde Apache Kullanımı
  • Novell NetWare ile Apache Kullanımı
  • HPUX üzerinde Yüksek Başarımlı HTTP Sunucusu Çalıştırma
  • Apache EBCDIC Portu

Apache HTTP Sunucusu ve Desteklenen Programlar

  • Genel Bakış
  • Kılavuz Sayfası: httpd
  • Kılavuz Sayfası: ab
  • Kılavuz Sayfası: apachectl
  • Kılavuz Sayfası: apxs
  • Kılavuz Sayfası: configure
  • Kılavuz Sayfası: dbmmanage
  • Kılavuz Sayfası: fcgistarter
  • Kılavuz Sayfası: htcacheclean
  • Kılavuz Sayfası: htdbm
  • Kılavuz Sayfası: htdigest
  • Kılavuz Sayfası: htpasswd
  • Kılavuz Sayfası: httxt2dbm
  • Kılavuz Sayfası: logresolve
  • Kılavuz Sayfası: log_server_status
  • Kılavuz Sayfası: rotatelogs
  • Kılavuz Sayfası: split-logfile
  • Kılavuz Sayfası: suexec
  • Diğer Programlar

Çeşitli Belgeler

  • Genel Bakış
  • Başarım Arttırma İpuçları
  • Güvenlik İpuçları
  • İlgili Standartlar
  • Parola Şifreleme Çeşitleri

Apache Modülleri

  • Apache modüllerini tanımlamakta kullanılan terimlerin açıklamaları
  • Apache yönergelerini tanımlamakta kullanılan terimlerin açıklamaları
  • Apache Temel Özellikleri
  • Apache MPM Ortak Yönergeleri
  • Apache MPM event
  • Apache MPM netware
  • Apache MPM os2
  • Apache MPM prefork
  • Apache MPM winnt
  • Apache MPM worker
  • Apache Modülü mod_access_compat
  • Apache Modülü mod_actions
  • Apache Modülü mod_alias
  • Apache Modülü mod_allowmethods
  • Apache Modülü mod_asis
  • Apache Modülü mod_auth_basic
  • Apache Modülü mod_auth_digest
  • Apache Modülü mod_auth_form
  • Apache Modülü mod_authn_anon
  • Apache Modülü mod_authn_core
  • Apache Modülü mod_authn_dbd
  • Apache Modülü mod_authn_dbm
  • Apache Modülü mod_authn_file
  • Apache Modülü mod_authn_socache
  • Apache Modülü mod_authnz_fcgi
  • Apache Modülü mod_authnz_ldap
  • Apache Modülü mod_authz_core
  • Apache Modülü mod_authz_dbd
  • Apache Modülü mod_authz_dbm
  • Apache Modülü mod_authz_groupfile
  • Apache Modülü mod_authz_host
  • Apache Modülü mod_authz_owner
  • Apache Modülü mod_authz_user
  • Apache Modülü mod_autoindex
  • Apache Modülü mod_buffer
  • Apache Modülü mod_cache
  • Apache Modülü mod_cache_disk
  • Apache Modülü mod_cache_socache
  • Apache Modülü mod_cern_meta
  • Apache Modülü mod_cgi
  • Apache Modülü mod_cgid
  • Apache Modülü mod_charset_lite
  • Apache Modülü mod_data
  • Apache Modülü mod_dav
  • Apache Modülü mod_dav_fs
  • Apache Modülü mod_dav_lock
  • Apache Modülü mod_dbd
  • Apache Modülü mod_deflate
  • Apache Modülü mod_dialup
  • Apache Modülü mod_dir
  • Apache Modülü mod_dumpio
  • Apache Modülü mod_echo
  • Apache Modülü mod_env
  • Apache Modülü mod_example_hooks
  • Apache Modülü mod_expires
  • Apache Modülü mod_ext_filter
  • Apache Modülü mod_file_cache
  • Apache Modülü mod_filter
  • Apache Modülü mod_headers
  • Apache Modülü mod_heartbeat
  • Apache Modülü mod_heartmonitor
  • Apache Modülü mod_http2
  • Apache Modülü mod_ident
  • Apache Modülü mod_imagemap
  • Apache Modülü mod_include
  • Apache Modülü mod_info
  • Apache Modülü mod_isapi
  • Apache Modülü mod_lbmethod_bybusyness
  • Apache Modülü mod_lbmethod_byrequests
  • Apache Modülü mod_lbmethod_bytraffic
  • Apache Modülü mod_lbmethod_heartbeat
  • Apache Modülü mod_ldap
  • Apache Modülü mod_log_config
  • Apache Modülü mod_log_debug
  • Apache Modülü mod_log_forensic
  • Apache Modülü mod_logio
  • Apache Modülü mod_lua
  • Apache Modülü mod_macro
  • Apache Modülü mod_mime
  • Apache Modülü mod_mime_magic
  • Apache Modülü mod_negotiation
  • Apache Modülü mod_nw_ssl
  • Apache Modülü mod_privileges
  • Apache Modülü mod_proxy
  • Apache Modülü mod_proxy_ajp
  • Apache Modülü mod_proxy_balancer
  • Apache Modülü mod_proxy_connect
  • Apache Modülü mod_proxy_express
  • Apache Modülü mod_proxy_fcgi
  • Apache Modülü mod_proxy_fdpass
  • Apache Modülü mod_proxy_ftp
  • Apache Modülü mod_proxy_html
  • Apache Modülü mod_proxy_http
  • Apache Modülü mod_proxy_scgi
  • Apache Modülü mod_proxy_wstunnel
  • Apache Modülü mod_ratelimit
  • Apache Modülü mod_reflector
  • Apache Modülü mod_remoteip
  • Apache Modülü mod_reqtimeout
  • Apache Modülü mod_request
  • Apache Modülü mod_rewrite
  • Apache Modülü mod_sed
  • Apache Modülü mod_session
  • Apache Modülü mod_session_cookie
  • Apache Modülü mod_session_crypto
  • Apache Modülü mod_session_dbd
  • Apache Modülü mod_setenvif
  • Apache Modülü mod_slotmem_plain
  • Apache Modülü mod_slotmem_shm
  • Apache Modülü mod_so
  • Apache Modülü mod_socache_dbm
  • Apache Modülü mod_socache_dc
  • Apache Modülü mod_socache_memcache
  • Apache Modülü mod_socache_shmcb
  • Apache Modülü mod_speling
  • Apache Modülü mod_ssl
  • Apache Modülü mod_status
  • Apache Modülü mod_substitute
  • Apache Modülü mod_suexec
  • Apache Modülü mod_unique_id
  • Apache Modülü mod_unixd
  • Apache Modülü mod_userdir
  • Apache Modülü mod_usertrack
  • Apache Modülü mod_version
  • Apache Modülü mod_vhost_alias
  • Apache Modülü mod_watchdog
  • Apache Modülü mod_xml2enc

Geliştirici Belgeleri

  • Genel Bakış
  • Apache API Bilgileri
  • Apache HTTPD 2.4'te API güncellemeleri
  • Apache HTTPD 2.4 için Modül Geliştirme
  • Apache HTTPD'nin Belgelendirilmesi
  • Apache 2.x Kullanıcı İşlevleri
  • Modüllerin 1.3’ten Apache 2.x’e Dönüştürülmesi
  • 2.x’de İsteklerin İşlenmesi
  • 2.x’de Süzgeçler Nasıl Çalışır
  • 2.x'de çıktı süzgeçleri için yol göstericiler
  • 2.x'de Çok Evrelilik Konuları

Terimler ve Dizin

  • Terimler
  • Modül Dizini
  • Yönerge Dizini
  • Hızlı Yönerge Kılavuzu

Copyright 2016 The Apache Software Foundation.
Apache License, Version 2.0 altında lisanslıdır.