Apache HTTP Server Version 2.2
Apache HTTP Server Version 2.2
아파치가 특정 주소와 포트에서 서비스하도록 설정하기.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
아파치를 시작하면 아파치는 컴퓨터의 어떤 포트와 주소에 연결하여, 들어오는 요청을 기다린다. 기본적으로 아파치는 컴퓨터의 모든 주소에서 기다린다. 그러나 아파치가 특정 포트나 선택한 주소만을 기다리게 해야할 경우가 있다. 또 이 문제는 아파치가 어떻게 다른 IP 주소, 호스트명, 포트에 반응할지를 결정하는 가상호스트 기능과도 관련되있다.
Listen 지시어는
서버가 특정 포트나 주소와 포트 조합에서만 요청을 받게
한다. Listen
지시어에 포트 번호만 지정하면, 서버는 모든 인터페이스에서
지정한 포트를 기다린다. 여러 Listen 지시어로 기다릴 여러
주소와 포트를 지정할 수도 있다. 서버는 열거한 주소와 포트로
요청이 들어오면 응답한다.
예를 들어, 서버가 80번과 8000번 포트 모두에서 연결을 받도록 하려면:
Listen 80
Listen 8000
서버가 지정한 두 인터페이스와 포트에서 연결을 기다리도록 하려면,
Listen 192.170.2.1:80
Listen 192.170.2.5:8000
IPv6 주소는 다음과 같이 대괄호로 묶어야 한다:
Listen [2001:db8::a00:20ff:fea7:ccea]:80
IPv6를 구현한 플래폼이 늘고 있고 APR이 이들 플래폼 대부분에서 IPv6를 지원하기때문에, 아파치는 IPv6 소켓을 할당하여 IPv6로 받은 요청을 처리할 수 있다.
아파치 관리자에게 복잡한 부분은 IPv6 소켓이 IPv4 연결과 IPv6 연결을 모두 처리할 수 있느냐는 점이다. 대부분의 플래폼에서는 IPv4-대응(mapped) IPv6 주소를 사용하여 IPv6 소켓에서 IPv4 연결을 받지만, FreeBSD와 NetBSD와 OpenBSD은 시스템전체 정책때문에 기본적으로 허용하지 않는다. 그러나 기본적으로 허용하지않는 시스템이라도 아파치를 위해 특별한 설정 파라미터로 변경할 수 있다.
반면 리눅스와 Tru64 같은 일부 플래폼에서 IPv4와 IPv6을
모두 처리하려면 대응 주소를 사용해야만
한다. 아파치가 최소한의 소켓을 사용하여 IPv4 연결과 IPv6
연결을 모두 받도록하려면, IPv4-대응 IPv6 주소를 사용하고
configure 옵션
--enable-v4-mapped를 지정한다.
--enable-v4-mapped는 FreeBSD, NetBSD, OpenBSD를
제외한 모든 플래폼에서 기본값이고, 아마도 당신의 아파치도
마찬가지일 것이다.
플래폼과 APR의 지원여부와 관계없이 아파치가 IPv4 연결만을
받도록하려면, 다음 예제와 같이 모든 Listen 지시어에 IPv4 주소를
사용한다:
Listen 0.0.0.0:80
Listen 192.170.2.1:80
플래폼에서 지원하며 아파치가 서로 다른 소켓으로 IPv4
연결과 IPv6 연결을 받도록하려면 (즉 IPv4-대응 주소를 사용하지
않으려면), configure
옵션 --disable-v4-mapped를
지정한다. --disable-v4-mapped는 FreeBSD, NetBSD,
OpenBSD에서 기본값이다.
Listen은
가상호스트를 만들지 않는다. 이는 단지 주서버가
어떤 주소와 포트를 기다릴지만 알려준다. <VirtualHost> 지시어를
사용하지 않으면, 서버는 받은 모든 요청을 똑같이 처리한다.
그러나 <VirtualHost>로 여러 주소와 포트에
대해 다른 행동을 지정할 수 있다. 가상호스트를 만들려면
먼저 서버에게 사용할 주소와 포트를 알려줘야 한다. 그리고
특정 주소와 포트에 대한 가상호스트의 행동을 지정할
<VirtualHost>
섹션이 필요하다. 주서버가 기다리지않는 주소와 포트를 사용하는
<VirtualHost>는
접근할 수 없음을 주의하라.
Apache HTTP Server Version 2.2
This document supplements the mod_cache,
mod_disk_cache, mod_mem_cache,
mod_file_cache and htcacheclean reference documentation.
It describes how to use Apache's caching features to accelerate web and
proxy serving, while avoiding common problems and misconfigurations.
As of Apache HTTP server version 2.2 mod_cache
and mod_file_cache are no longer marked
experimental and are considered suitable for production use. These
caching architectures provide a powerful means to accelerate HTTP
handling, both as an origin webserver and as a proxy.
mod_cache and its provider modules
mod_mem_cache and mod_disk_cache
provide intelligent, HTTP-aware caching. The content itself is stored
in the cache, and mod_cache aims to honour all of the various HTTP
headers and options that control the cachability of content. It can
handle both local and proxied content. mod_cache
is aimed at both simple and complex caching configurations, where
you are dealing with proxied content, dynamic local content or
have a need to speed up access to local files which change with
time.
mod_file_cache on the other hand presents a more
basic, but sometimes useful, form of caching. Rather than maintain
the complexity of actively ensuring the cachability of URLs,
mod_file_cache offers file-handle and memory-mapping
tricks to keep a cache of files as they were when Apache was last
started. As such, mod_file_cache is aimed at improving
the access time to local static files which do not change very
often.
As mod_file_cache presents a relatively simple
caching implementation, apart from the specific sections on CacheFile and MMapStatic, the explanations
in this guide cover the mod_cache caching
architecture.
To get the most from this document, you should be familiar with the basics of HTTP, and have read the Users' Guides to Mapping URLs to the Filesystem and Content negotiation.
| Related Modules | Related Directives |
|---|---|
There are two main stages in mod_cache that can
occur in the lifetime of a request. First, mod_cache
is a URL mapping module, which means that if a URL has been cached,
and the cached version of that URL has not expired, the request will
be served directly by mod_cache.
This means that any other stages that might ordinarily happen
in the process of serving a request -- for example being handled
by mod_proxy, or mod_rewrite --
won't happen. But then this is the point of caching content in
the first place.
If the URL is not found within the cache, mod_cache
will add a filter to the request handling. After
Apache has located the content by the usual means, the filter will be run
as the content is served. If the content is determined to be cacheable,
the content will be saved to the cache for future serving.
If the URL is found within the cache, but also found to have expired,
the filter is added anyway, but mod_cache will create
a conditional request to the backend, to determine if the cached version
is still current. If the cached version is still current, its
meta-information will be updated and the request will be served from the
cache. If the cached version is no longer current, the cached version
will be deleted and the filter will save the updated content to the cache
as it is served.
When caching locally generated content, ensuring that
UseCanonicalName is set to
On can dramatically improve the ratio of cache hits. This
is because the hostname of the virtual-host serving the content forms
a part of the cache key. With the setting set to On
virtual-hosts with multiple server names or aliases will not produce
differently cached entities, and instead content will be cached as
per the canonical hostname.
Because caching is performed within the URL to filename translation phase, cached documents will only be served in response to URL requests. Ordinarily this is of little consequence, but there is one circumstance in which it matters: If you are using Server Side Includes;
<!-- The following include can be cached --> <!--#include virtual="/footer.html" --> <!-- The following include can not be cached --> <!--#include file="/path/to/footer.html" -->
If you are using Server Side Includes, and want the benefit of speedy
serves from the cache, you should use virtual include
types.
The default expiry period for cached entities is one hour, however
this can be easily over-ridden by using the CacheDefaultExpire directive. This
default is only used when the original source of the content does not
specify an expire time or time of last modification.
If a response does not include an Expires header but does
include a Last-Modified header, mod_cache
can infer an expiry period based on the use of the CacheLastModifiedFactor directive.
For local content, mod_expires may be used to
fine-tune the expiry period.
The maximum expiry period may also be controlled by using the
CacheMaxExpire.
When content expires from the cache and is re-requested from the backend or content provider, rather than pass on the original request, Aoache will use a conditional request instead.
HTTP offers a number of headers which allow a client, or cache to discern between different versions of the same content. For example if a resource was served with an "Etag:" header, it is possible to make a conditional request with an "If-Match:" header. If a resource was served with a "Last-Modified:" header it is possible to make a conditional request with an "If-Modified-Since:" header, and so on.
When such a conditional request is made, the response differs depending on whether the content matches the conditions. If a request is made with an "If-Modified-Since:" header, and the content has not been modified since the time indicated in the request then a terse "304 Not Modified" response is issued.
If the content has changed, then it is served as if the request were not conditional to begin with.
The benefits of conditional requests in relation to caching are twofold. Firstly, when making such a request to the backend, if the content from the backend matches the content in the store, this can be determined easily and without the overhead of transferring the entire resource.
Secondly, conditional requests are usually less strenuous on the
backend. For static files, typically all that is involved is a call
to stat() or similar system call, to see if the file has
changed in size or modification time. As such, even if Apache is
caching local content, even expired content may still be served faster
from the cache if it has not changed. As long as reading from the cache
store is faster than reading from the backend (e.g. an in-memory cache
compared to reading from disk).
As mentioned already, the two styles of caching in Apache work
differently, mod_file_cache caching maintains file
contents as they were when Apache was started. When a request is
made for a file that is cached by this module, it is intercepted
and the cached file is served.
mod_cache caching on the other hand is more
complex. When serving a request, if it has not been cached
previously, the caching module will determine if the content
is cacheable. The conditions for determining cachability of
a response are;
CacheEnable and CacheDisable directives.CacheIgnoreNoLastMod
directive has been used to require otherwise.CacheStorePrivate has been
used to require otherwise.CacheStoreNoStore has been
used.In short, any content which is highly time-sensitive, or which varies depending on the particulars of the request that are not covered by HTTP negotiation, should not be cached.
If you have dynamic content which changes depending on the IP address of the requester, or changes every 5 minutes, it should almost certainly not be cached.
If on the other hand, the content served differs depending on the values of various HTTP headers, it is possible that it might be possible to cache it intelligently through the use of a "Vary" header.
If a response with a "Vary" header is received by
mod_cache when requesting content by the backend it
will attempt to handle it intelligently. If possible,
mod_cache will detect the headers attributed in the
"Vary" response in future requests and serve the correct cached
response.
If for example, a response is received with a vary header such as;
Vary: negotiate,accept-language,accept-charset
mod_cache will only serve the cached content to
requesters with matching accept-language and accept-charset headers
matching those of the original request.
Using mod_cache is very much like having a built
in reverse-proxy. Requests will be served by the caching module unless
it determines that the backend should be queried. When caching local
resources, this drastically changes the security model of Apache.
As traversing a filesystem hierarchy to examine potential
.htaccess files would be a very expensive operation,
partially defeating the point of caching (to speed up requests),
mod_cache makes no decision about whether a cached
entity is authorised for serving. In other words; if
mod_cache has cached some content, it will be served
from the cache as long as that content has not expired.
If, for example, your configuration permits access to a resource by IP
address you should ensure that this content is not cached. You can do this by
using the CacheDisable
directive, or mod_expires. Left unchecked,
mod_cache - very much like a reverse proxy - would cache
the content when served and then serve it to any client, on any IP
address.
As requests to end-users can be served from the cache, the cache itself can become a target for those wishing to deface or interfere with content. It is important to bear in mind that the cache must at all times be writable by the user which Apache is running as. This is in stark contrast to the usually recommended situation of maintaining all content unwritable by the Apache user.
If the Apache user is compromised, for example through a flaw in
a CGI process, it is possible that the cache may be targeted. When
using mod_disk_cache, it is relatively easy to
insert or modify a cached entity.
This presents a somewhat elevated risk in comparison to the other
types of attack it is possible to make as the Apache user. If you are
using mod_disk_cache you should bear this in mind -
ensure you upgrade Apache when security upgrades are announced and
run CGI processes as a non-Apache user using suEXEC if possible.
When running Apache as a caching proxy server, there is also the potential for so-called cache poisoning. Cache Poisoning is a broad term for attacks in which an attacker causes the proxy server to retrieve incorrect (and usually undesirable) content from the backend.
For example if the DNS servers used by your system running Apache are vulnerable to DNS cache poisoning, an attacker may be able to control where Apache connects to when requesting content from the origin server. Another example is so-called HTTP request-smuggling attacks.
This document is not the correct place for an in-depth discussion of HTTP request smuggling (instead, try your favourite search engine) however it is important to be aware that it is possible to make a series of requests, and to exploit a vulnerability on an origin webserver such that the attacker can entirely control the content retrieved by the proxy.
| Related Modules | Related Directives |
|---|---|
The act of opening a file can itself be a source of delay, particularly on network filesystems. By maintaining a cache of open file descriptors for commonly served files, Apache can avoid this delay. Currently Apache provides two different implementations of File-Handle Caching.
The most basic form of caching present in Apache is the file-handle
caching provided by mod_file_cache. Rather than caching
file-contents, this cache maintains a table of open file descriptors. Files
to be cached in this manner are specified in the configuration file using
the CacheFile
directive.
The
CacheFile directive
instructs Apache to open the file when Apache is started and to re-use
this file-handle for all subsequent access to this file.
CacheFile /usr/local/apache2/htdocs/index.html
If you intend to cache a large number of files in this manner, you must ensure that your operating system's limit for the number of open files is set appropriately.
Although using CacheFile
does not cause the file-contents to be cached per-se, it does mean
that if the file changes while Apache is running these changes will
not be picked up. The file will be consistently served as it was
when Apache was started.
If the file is removed while Apache is running, Apache will continue to maintain an open file descriptor and serve the file as it was when Apache was started. This usually also means that although the file will have been deleted, and not show up on the filesystem, extra free space will not be recovered until Apache is stopped and the file descriptor closed.
mod_mem_cache also provides its own file-handle
caching scheme, which can be enabled via the
CacheEnable directive.
CacheEnable fd /
As with all of mod_cache this type of file-handle
caching is intelligent, and handles will not be maintained beyond
the expiry time of the cached content.
| Related Modules | Related Directives |
|---|---|
Serving directly from system memory is universally the fastest method of serving content. Reading files from a disk controller or, even worse, from a remote network is orders of magnitude slower. Disk controllers usually involve physical processes, and network access is limited by your available bandwidth. Memory access on the other hand can take mere nano-seconds.
System memory isn't cheap though, byte for byte it's by far the most expensive type of storage and it's important to ensure that it is used efficiently. By caching files in memory you decrease the amount of memory available on the system. As we'll see, in the case of operating system caching, this is not so much of an issue, but when using Apache's own in-memory caching it is important to make sure that you do not allocate too much memory to a cache. Otherwise the system will be forced to swap out memory, which will likely degrade performance.
Almost all modern operating systems cache file-data in memory managed directly by the kernel. This is a powerful feature, and for the most part operating systems get it right. For example, on Linux, let's look at the difference in the time it takes to read a file for the first time and the second time;
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
Even for this small file, there is a huge difference in the amount of time it takes to read the file. This is because the kernel has cached the file contents in memory.
By ensuring there is "spare" memory on your system, you can ensure that more and more file-contents will be stored in this cache. This can be a very efficient means of in-memory caching, and involves no extra configuration of Apache at all.
Additionally, because the operating system knows when files are deleted or modified, it can automatically remove file contents from the cache when neccessary. This is a big advantage over Apache's in-memory caching which has no way of knowing when a file has changed.
Despite the performance and advantages of automatic operating system caching there are some circumstances in which in-memory caching may be better performed by Apache.
Firstly, an operating system can only cache files it knows about. If you are running Apache as a proxy server, the files you are caching are not locally stored but remotely served. If you still want the unbeatable speed of in-memory caching, Apache's own memory caching is needed.
mod_file_cache provides the
MMapStatic directive, which
allows you to have Apache map a static file's contents into memory at
start time (using the mmap system call). Apache will use the in-memory
contents for all subsequent accesses to this file.
MMapStatic /usr/local/apache2/htdocs/index.html
As with the
CacheFile directive, any
changes in these files will not be picked up by Apache after it has
started.
The MMapStatic
directive does not keep track of how much memory it allocates, so
you must ensure not to over-use the directive. Each Apache child
process will replicate this memory, so it is critically important
to ensure that the files mapped are not so large as to cause the
system to swap memory.
mod_mem_cache provides a HTTP-aware intelligent
in-memory cache. It also uses heap memory directly, which means that
even if MMap is not supported on your system,
mod_mem_cache may still be able to perform caching.
Caching of this type is enabled via;
# Enable memory caching CacheEnable mem / # Limit the size of the cache to 1 Megabyte MCacheSize 1024
| Related Modules | Related Directives |
|---|---|
mod_disk_cache provides a disk-based caching mechanism
for mod_cache. As with mod_mem_cache
this cache is intelligent and content will be served from the cache only
as long as it is considered valid.
Typically the module will be configured as so;
CacheRoot /var/cache/apache/ CacheEnable disk / CacheDirLevels 2 CacheDirLength 1
Importantly, as the cached files are locally stored, operating system in-memory caching will typically be applied to their access also. So although the files are stored on disk, if they are frequently accessed it is likely the operating system will ensure that they are actually served from memory.
To store items in the cache, mod_disk_cache creates
a 22 character hash of the url being requested. Thie hash incorporates
the hostname, protocol, port, path and any CGI arguments to the URL,
to ensure that multiple URLs do not collide.
Each character may be any one of 64-different characters, which mean
that overall there are 22^64 possible hashes. For example, a URL might
be hashed to xyTGxSMO2b68mBCykqkp1w. This hash is used
as a prefix for the naming of the files specific to that url within
the cache, however first it is split up into directories as per
the CacheDirLevels and
CacheDirLength
directives.
CacheDirLevels
specifies how many levels of subdirectory there should be, and
CacheDirLength
specifies how many characters should be in each directory. With
the example settings given above, the hash would be turned into
a filename prefix as
/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w.
The overall aim of this technique is to reduce the number of
subdirectories or files that may be in a particular directory,
as most file-systems slow down as this number increases. With
setting of "1" for
CacheDirLength
there can at most be 64 subdirectories at any particular level.
With a setting of 2 there can be 64 * 64 subdirectories, and so on.
Unless you have a good reason not to, using a setting of "1"
for CacheDirLength
is recommended.
Setting
CacheDirLevels
depends on how many files you anticipate to store in the cache.
With the setting of "2" used in the above example, a grand
total of 4096 subdirectories can ultimately be created. With
1 million files cached, this works out at roughly 245 cached
urls per directory.
Each url uses at least two files in the cache-store. Typically there is a ".header" file, which includes meta-information about the url, such as when it is due to expire and a ".data" file which is a verbatim copy of the content to be served.
In the case of a content negotiated via the "Vary" header, a ".vary" directory will be created for the url in question. This directory will have multiple ".data" files corresponding to the differently negotiated content.
Although mod_disk_cache will remove cached content
as it is expired, it does not maintain any information on the total
size of the cache or how little free space may be left.
Instead, provided with Apache is the htcacheclean tool which, as the name suggests, allows you to clean the cache periodically. Determining how frequently to run htcacheclean and what target size to use for the cache is somewhat complex and trial and error may be needed to select optimal values.
htcacheclean has two modes of operation. It can be run as persistent daemon, or periodically from cron. htcacheclean can take up to an hour or more to process very large (tens of gigabytes) caches and if you are running it from cron it is recommended that you determine how long a typical run takes, to avoid running more than one instance at a time.
Figure 1: Typical
cache growth / clean sequence.
Because mod_disk_cache does not itself pay attention
to how much space is used you should ensure that
htcacheclean is configured to
leave enough "grow room" following a clean.
Apache HTTP Server Version 2.2
이 문서는 아파치 웹서버를 설정하는 파일들을 설명한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
일반 문서 파일인 설정파일에 지시어를 사용하여 아파치를
설정한다. 주설정파일을 보통 httpd.conf라고
부른다. 이 파일의 위치는 컴파일시 정해지나, -f
명령행 옵션으로 지정해줄 수 있다. 또 다른 설정파일을 Include 지시어를 사용하여 포함할
수 있고, 와일드카드를 사용하여 많은 설정파일을 포함할 수도
있다. 이 경우 지시어를 어떤 설정파일에나 사용해도 된다.
주설정파일을 수정하면 아파치를 시작하거나 재시작한 이후에
반영된다.
서버는 mime 문서타입을 담은 파일도 읽는다. 파일명은
TypesConfig 지시어로
설정하고, 기본값은 mime.types이다.
아파치 설정파일은 한줄에 한 지시어를 사용한다. 줄 마지막 문자가 백슬래쉬 "\"이면 지시어가 다음 줄에서 계속됨을 뜻한다. 이 경우 백슬래쉬 뒤에 어떤 문자나 공백도 나오면 안된다.
설정파일의 지시어는 대소문자를 구별하지 않지만, 지시어의 아규먼트는 대소문자를 구별하는 경우가 있다. 해쉬문자 "#"로 시작하는 줄은 주석으로 무시한다. 주석을 설정 지시어와 같은 줄에 사용할 수 없다. 빈줄과 지시어 앞에 나오는 공백은 무시하므로, 간결하게 보이도록 지시어를 줄들임할(indent) 수 있다.
apachectl configtest나 -t 명령행
옵션을 사용하여 아파치를 실행하지 않고도 설정파일의 문법
오류를 검사할 수 있다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
아파치는 모듈화된 서버다. 이는 매우 기본적인 기능만이
서버 핵심에 포함되있음을 뜻한다. 아파치는 모듈을 읽어들여서 기능을
확장한다. 기본적으로 컴파일하면 서버에 base 모듈들이 포함된다.
서버를 동적으로 읽어들이는 모듈을
사용할 수 있게 컴파일하였다면 모듈을 따로 컴파일하여 아무때나
LoadModule 지시어로
추가할 수 있다. 그렇지 않으면 모듈을 추가하거나 빼기위해
아파치를 다시 컴파일해야 한다. 설정 지시어를 IfModule 블록으로 감싸서 특정
모듈이 있는 경우에만 선택적으로 처리할 수 있다.
현재 서버에 어떤 모듈이 컴파일되있는지 보려면 -l
명령행 옵션을 사용한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
주설정파일에 있는 지시어는 서버 전체에 적용된다. 지시어가
서버의 일부에만 적용되게 하려면 지시어를 <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch> 섹션 안에 두어야한다.
이 섹션들은 그들이 감싸는 지시어의 적용범위를 파일시스템이나
URL의 특정 위치로 한정한다. 또, 서로 겹쳐서 사용할 수 있기때문에
매우 세밀한 설정이 가능하다.
아파치는 여러 다른 웹사이트를 동시에 서비스하는
능력이 있다. 이를 가상호스트라고 한다.
지시어를
<VirtualHost>
섹션 안에 두어 특정 웹사이트에만 지시어를 적용할 수 있다.
지시어는 대부분 어떤 섹션에 나와도 되지만, 어떤 지시어는 특정 장소에서 의미가 없다. 예를 들어 프로세스 생성을 조절하는 지시어는 주서버설정 장소에서만 사용할 수 있다. 지시어가 어떤 섹션에 위치할 수 있는지 알려면 지시어의 사용장소를 확인하라. 더 자세한 정보는 어떻게 Directory, Location, Files 섹션이 동작하나를 참고하라.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
아파치는 특별한 파일을 사용하여 설정을
나눠서(분권적으로) 관리할 수 있다. 이 특별한 파일을 보통
.htaccess라고 부르지만, 이름은 AccessFileName 지시어로
지정할 수 있다. .htaccess 파일에 있는 지시어는
파일이 있는 디렉토리와 모든 하위디렉토리에 적용된다.
.htaccess 파일은 주설정파일과 같은 문법을
따른다. .htaccess 파일은 매 요청때마다 읽기때문에
파일을 수정하면 즉시 효과를 볼 수 있다.
어떤 지시어를 .htaccess 파일에 사용할 수
있는지 알려면 지시어의 사용장소를
확인하라. 서버 관리자는 주설정파일의 AllowOverride 지시어로
.htaccess 파일에 어떤 지시어를 사용할 수 있는지
조절할 수 있다.
.htaccess 파일에 대한 더 자세한 정보는
.htaccess 투토리얼을
참고하라.
Apache HTTP Server Version 2.2
아파치는 HTTP/1.1 규약에 기술된 내용협상(content negotiation)을 지원한다. 내용협상은 media type, 언어, 문자집합, 인코딩 등에 대해 브라우저가 제공한 선호도에 따라 자원의 가장 적합한 표현을 선택한다. 또 불완전한 협상 정보를 보내는 브라우저의 요청을 지능적으로 처리하는 기능도 있다.
기본적으로 컴파일되는 mod_negotiation
모듈이 내용협상 기능을 제공한다.
자원은 여러 다른 표현을 가질 수 있다. 예를 들어, 다른 언어나 다른 media type 혹은 둘 모두가 다른 표현들이 있을 수 있다. 가장 적당한 표현을 선택하는 한가지 방법은 사용자에게 목록 페이지를 보여주고 선택하게 하는 것이다. 그러나 서버가 자동으로 선택하는 것도 가능하다. 이는 브라우저가 요청의 일부로 그들이 선호하는 표현에 대한 정보를 보내기때문에 가능하다. 예를 들어, 브라우저는 가능한한 불어로, 그러나 없다면 영어로 정보를 보고싶다고 알려줄 수 있다. 브라우저는 요청의 헤더로 그들의 기호를 나타낸다. 오직 불어로된 표현만을 요청한다면 브라우저는 다음과 같이 보낸다.
Accept-Language: fr
이런 기호는 표현이 언어별로 다를 경우에만 고려된다.
다음은 더 복잡한 요청의 예로 브라우저가 불어와 영어를 받을 수 있지만, 불어를 더 선호하고, 여러 media type을 받을 수 있지만, 일반 텍스트 보다는 HTML, 다른 media type 보다는 GIF와 JPEG을 선호한다고 알려준다.
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
아파치는 HTTP/1.1 규약에 정의된 '서버 주도(server driven)'
내용협상을 지원한다. 아파치는 Accept,
Accept-Language, Accept-Charset,
Accept-Encoding 요청 헤더를 모두 지원한다.
또, 아파치는 RFC 2295와 RFC 2296에 정의된 실험적인 내용협상인
'자연스러운(transparent)' 요청 헤더도 지원한다. 그러나 이
RFC에 정의된 '기능 협상(feature negotiation)'은 지원하지
않는다.
자원(resource)은 (RFC 2396) URI로 구별하는 개념적인 존재다. 아파치와 같은 웹서버는 자원의 표현(representations)을 제공한다. 표현은 지정된 media type, 문자집합, 인코딩 등을 가진 바이트들로 되있다. 자원은 여러 표현과 (때로는 없을 수도 있다) 연관된다. 자원에 여러 표현이 있다면 자원을 협상가능하다고(negotiable) 부르며, 이때 각 표현을 변형(variant)이라고 한다. 협상가능한 자원의 변형 종류를 협상의 범위(dimension)라고 한다.
자원을 협상하기위해 서버는 각 변형에 대한 정보가 필요하다. 다음 두가지 방법중 하나로 정보를 얻는다:
*.var 파일) 사용하거나,type map은 type-map이란 핸들러와 연결된
(혹은 이전 아파치 설정과 호환을 위해 MIME type이
application/x-type-map인) 문서다. 이 기능을
사용하려면 설정에서 type-map 핸들러에 대한
파일 확장자를 지정해야 한다. 서버 설정파일에 다음과 같이
설정하는 것이 좋다.
AddHandler type-map .var
Type map 파일은 해당하는 자원과 이름이 같아야 하고,
각 변형에 대한 항목이 있어야 한다. 항목은 여러 HTTP형식
헤더 줄로 구성된다. 변형에 대한 각각의 항목들은 빈줄로
구분한다. 항목안에서 빈줄을 사용할 수 없다. (이렇게 할
필요가 없고, 있어도 무시하지만) 여러 항목이 공통으로 가지고
있는 내용으로 map 파일을 시작하는 것이 보통이다. 다음은
map 파일 예다. 이 파일의 이름은 foo.var로,
foo라는 자원을 설명한다.
URI: foo
URI: foo.en.html
Content-type: text/html
Content-language: en
URI: foo.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de
typemap 파일이 파일명 확장자 보다, 심지어 Multiviews를 사용하여도, 우선권을 가짐을 주의하라. 변형이 서로 다른 품질을 가진다면, 다음과 같이 (JPEG, GIF, ASCII-art에 해당하는) media type에 "qs" 파라미터로 품질(source quality)을 표시할 수 있다:
URI: foo
URI: foo.jpeg
Content-type: image/jpeg; qs=0.8
URI: foo.gif
Content-type: image/gif; qs=0.5
URI: foo.txt
Content-type: text/plain; qs=0.01
qs 값은 0.000에서 1.000 사이다. qs 값이 0.000인 변형은 절대 선택되지 않음을 주의하라. 'qs' 값이 없는 변형은 1.0으로 취급된다. qs 값은 클라이언트의 능력과는 관계없이 다른 변형들과 비교하여 그 변형의 상대적인 '품질'을 나타낸다. 예를 들어, 사진을 나타내려는 경우 JPEG 파일이 ASCII 파일보다는 항상 높은 품질을 가진다. 그러나 자원이 원래 ASCII art였다면 ASCII 표현이 JPEG 표현보다 더 높은 품질을 가질 수 있다. 그러므로 어떤 변형의 qs 값은 표현하려는 자원의 성질에 따라 다르다.
지원하는 모든 헤더 목록은 mod_negotation typemap 문서를 참고하라.
MultiViews는 디렉토리별 옵션이므로,
httpd.conf의
<Directory>,
<Location>,
<Files>
섹션 혹은 (AllowOverride가
적절히 설정되었다면) .htaccess 파일의
Options 지시어에 설정할
수 있다. Options All은 MultiViews를
포함하지않음을 주의하라. 따로 직접 써줘야 한다.
MultiViews를 사용하면 다음과 같은 일이 일어난다:
서버가 /some/dir/foo에 대한 요청을 받고
/some/dir/foo에 MultiViews가 동작하며
/some/dir/foo가 존재하지 않을 경우,
서버는 디렉토리에서 이름이 foo.*인 파일들을 모든 포함하는
가상의 type map을 만든다. 클라이언트가 요청한 media type과
content-encoding을 가지고 이중에 가장 적합한 것을 선택한다.
MultiViews는 서버가 디렉토리를 참조할때
파일을 찾는 DirectoryIndex 지시어에도
적용된다. 설정파일이 다음과 같다면,
DirectoryIndex index
index.html과 index.html3이
모두 있다면 서버는 이둘 중에 하나를 결정한다. 둘 모두 없고
index.cgi가 있다면, 서버는 그것을 실행한다.
디렉토리를 읽을때 파일중 하나가 Charset, Content-Type,
Language, Encoding를 판단하는 mod_mime이 모르는
확장자를 가진다면, 결과는 MultiViewsMatch 지시어 설정에
달렷다. 이 지시어는 핸들러, 필터, 다른 확장형들이 MultiViews
협상에 참여할지 여부를 결정한다.
아파치가 type-map 파일이나 디렉토리에 있는 파일명들로 주어진 자원에 대한 변형 목록을 얻게되면 '최적의' 변형을 결정하기위해 두 방법중 하나를 사용한다. 아파치 내용협상 기능을 사용하기위해 정확히 협상이 어떻게 일어나는지 자세히 알 필요는 없다. 그러나 궁금한 사람을 위해 이 방법을 설명한다.
두가지 협상방법이 있다:
| 범위 | 설명 |
|---|---|
| Media Type | 브라우저는 Accept 헤더로 선호를 나타낸다.
각 항목은 품질계수를 가질 수 있다. 변형의 설명도 품질계수를
("qs" 파라미터) 가질 수 있다. |
| Language | 브라우저는 Accept-Language 헤더로 선호를
나타낸다. 각 항목은 품질계수를 가질 수 있다. 변형은
여러 언어를 가질 (혹은 아무 언어도 없을) 수 있다. |
| Encoding | 브라우저는 Accept-Encoding 헤더로 선호를
나타낸다. 각 항목은 품질계수를 가질 수 있다. |
| Charset | 브라우저는 Accept-Charset 헤더로 선호를
나타낸다. 각 항목은 품질계수를 가질 수 있다. 변형은
media type의 파라미터로 문자집합을 나타낼 수 있다. |
아파치는 브라우저에게 보낼 '최적의' 변형을 (있다면) 선택하기위해 아래 알고리즘을 사용한다. 이 알고리즘은 변경할 수 없다. 다음와 같이 동작한다:
Accept 헤더의 품질계수와 변형의
media type에 대한 품질값을 곱하여 가장 높은 값을
가진 변형을 선택한다.Accept-Language 헤더에 (있다면)
나온 언어의 순서 혹은 LanguagePriority
지시어에 (있다면) 나온 언어의 순서를 가지고 가장
적합한 언어를 가진 변형을 선택한다.Accept-Charset 헤더를 가지고 가장
적합한 charset media 파라미터를 가진 변형을 찾는다.
헤더가 없다면 ISO-8859-1 문자집합을 가장 선호한다.
text/* media type을 가지지만 명시적으로
특정 문자집합과 연결되지않은 변형은 ISO-8859-1로
가정한다.Vary는 협상의 범위를
나타내게 된다. (브라우저와 캐쉬는 자원을 캐쉬할때 이 정보를
사용할 수 있다.) 끝.Vary 헤더는 변형의 범위를 나타낸다.아파치는 종종 위의 아파치 협상 알고리즘을 엄격히 지키지않고
품질계수를 변경한다. 이유는 완전하고 정확한 정보를 보내지않는
브라우저에게 (알고리즘의) 더 나은 결과를 보내기 위해서다.
널리 쓰이는 브라우저중 일부는 자주 잘못된 변형을 선택하도록
Accept 헤더를 보낸다. 브라우저가 완전하고 올바른
정보를 보낸다면, 조작을 하지않는다.
Accept: 요청 헤더는 media type에 대한 선호를
나타낸다. 또, *는 어떤 문자열이라도 가능하기때문에 "image/*"나
"*/*" 같이 '와일드카드' media type을 사용할 수도 있다. 그래서
다음과 같은 요청은:
Accept: image/*, */*
"image/"로 시작하는 어떤 type과 다른 어떤 type도 가능함을 의미한다. 어떤 브라우저는 자신이 실제로 다룰 수 있는 type에 추가로 와일드카드를 보낸다. 예를 들면:
Accept: text/html, text/plain, image/gif, image/jpeg, */*
이유는 직접 열거한 type을 선호하지만 다른 표현이 있다면 그것도 괜찮음을 나타내기 위해서다. 브라우저가 실제로 원한 것은 다음과 같이 명시적으로 품질값을 사용한 것이다.
Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
직접 열거한 type은 품질계수가 없어서 기본값인 (가장 높은) 1.0을 가진다. 와일드카드 */*는 낮은 선호도 0.01을 가지므로 직접 열거한 type에 맞는 변형이 없는 경우에만 다른 type들이 사용된다.
Accept: 헤더에 q 계수가 전혀 없고
"*/*"가 있다면, 아파치는 바람직한 행동을 위해 q 값으로 0.01을
지정한다. 또, "type/*" 형태의 와일드카드에는 ("*/*"보다는
더 선호하도록) 0.02를 지정한다. Accept: 헤더에서
q 계수를 가지는 media type이 있다면 이런 특별한 값을 추가하지
않는다. 그래서 명시적인 정보를 보내는 브라우저의
요청은 요청한데로 처리한다.
아파치 2.0은 언어 협상이 실패한 경우 부드럽게 복구하기위해 협상 알고리즘에 새로 예외를 몇개 추가했다.
클라이언트가 서버에 페이지를 요청했을때 서버가 브라우저가
보낸 Accept-language에 맞는 페이지를 단 한개만
찾으면 문제가 없지만, 그러지 않은 경우 서버는 클라이언트에게
"No Acceptable Variant"나 "Multiple Choices" 응답을 보낸다.
이런 오류문을 피하기위해 이 경우 Accept-language를
무시하고 클라이언트의 요청에 명확히 맞지는 않지만 문서를
보내도록 아파치를 설정할 수 있다. ForceLanguagePriority
지시어는 서버가 이런 오류문중 하나 혹은 둘다를 무시하고
LanguagePriority
지시어로 판단하도록 한다.
또, 서버는 맞는 언어를 못찾은 경우 부모언어를 찾을 수도
있다. 예를 들어 클라이언트가 영국영어를 뜻하는
en-GB 언어로 문서를 요청한 경우, HTTP/1.1 표준에
따르면 서버는 en으로만 표시된 문서를 일반적으로
선택하지 못한다. (그래서 영국영어를 이해하는 독자가 일반적인
영어도 이해할 수 있으므로 Accept-Language 헤더에
en-GB만 포함하고 en을 포함하지않으면
거의 확실히 잘못된 설정임을 유의하라. 불행히도 현재 많은
클라이언트들은 이런 식으로 기본설정되있다.) 다른 언어를
찾지 못하여 서버가 "No Acceptable Variants" 오류를 보내거나
LanguagePriority로
돌아가야 한다면, 서버는 하위언어 규약을 무시하고
en-GB를 en 문서에 대응한다.
암묵적으로 아파치는 부모언어를 매우 낮은 품질값으로
클라이언트의 허용언어 목록에 추가한다. 그러나 클라이언트가
"en-GB; q=0.9, fr; q=0.8"을 요청하고 서버에 "en"과 "fr"
문서가 있다면, "fr" 문서가 선택됨을 주의하라. 이는 HTTP/1.1
표준을 지키고, 올바로 설정된 클라이언트와 효율적으로
동작하기위함이다.
사용자가 선호하는 언어를 알아내기위한 (쿠키나 특별한
URL-경로 같은) 고급 기법을 지원하기위해 아파치 2.0.47부터
mod_negotiation은 prefer-language라는
환경변수를 인식한다. 이 환경변수가
존재하고 적절한 언어태그를 포함한다면,
mod_negotiation은 해당하는 변형을 선택하려고
시도한다. 그런 변형이 없다면 일반적인 협상과정을 시작한다.
SetEnvIf Cookie "language=(.+)" prefer-language=$1
아파치는 다음과 같이 자연스러운 내용확장 프로토콜을 (RFC 2295)
확장한다. 변형 목록의 새로운 {encoding ..}는 특정
content-encoding을 가진 변형만을 지칭한다. RVSA/1.0 알고리즘은
(RFC 2296) 목록에서 인코딩된 변형을 인식할 수 있고, 인코딩이
Accept-Encoding 요청 헤더에 맞는 경우 인코딩된
변형들도 후보로 사용하도록 확장되었다. RVSA/1.0 구현은 최적의
변형을 찾기 전에 계산된 품질계수를 소수점 5자리에서 반올림하지
않는다.
언어(language) 협상을 사용한다면 파일은 여러 확장자를 가지고 확장자의 순서는 보통 관계없으므로 파일명에 여러 다른 이름규칙을 사용할 수 있다. (자세한 내용은 mod_mime 문서를 참고하라.)
전형적인 파일은 MIME-type 확장자 (예를 들어,
html), 경우에 따라 encoding 확장자 (예를
들어, gz), 파일에 여러 언어 변형이 있는
경우 물론 언어 확장자를 (예를 들어, en)
가진다.
예제:
다음은 몇몇 파일명과 그 파일에 대한 유효하고 유효하지않은 하이퍼링크를 보인다:
| 파일명 | 유효한 하이퍼링크 | 유효하지않은 하이퍼링크 |
|---|---|---|
| foo.html.en | foo foo.html |
- |
| foo.en.html | foo | foo.html |
| foo.html.en.gz | foo foo.html |
foo.gz foo.html.gz |
| foo.en.html.gz | foo | foo.html foo.html.gz foo.gz |
| foo.gz.html.en | foo foo.gz foo.gz.html |
foo.html |
| foo.html.gz.en | foo foo.html foo.html.gz |
foo.gz |
위 표를 보면 하이퍼링크에 어떤 확장자도 없는 이름을
(예를 들어, foo) 항상 사용할 수 있음을
알 수 있다. 이 경우 장점은 문서의 실제 종류를 숨길 수 있어서,
예를 들어 하이러링크 참조를 수정하않고
html 파일을 shtml이나
cgi로 변경할 수 있다는 점이다.
계속 하이퍼링크에 MIME-type을 (예를 들어,
foo.html) 사용하고 싶다면 (encoding 확장자가
있다면 이것도 포함하여) 언어 확장자를 MIME-type 확장자보다
오른쪽에 (예를 들어, foo.html.en)
두어야한다.
캐쉬가 표현을 저장하면 표현과 요청 URL을 연관시킨다. 다음번 그 URL을 요청하면 캐쉬는 저장된 표현을 사용한다. 그러나 서버와 협상이 가능한 자원인 경우 첫번째 요청한 변형만 캐쉬되어 이후 요청은 캐쉬된 잘못된 응답을 얻을 수 있다. 이를 막기위해 아파치는 보통 내용협상후 반환되는 모든 요청에 HTTP/1.0 클라이언트가 캐쉬를 못하도록 표시를 한다. 또, 아파치는 협상한 응답의 캐쉬를 허용하는 HTTP/1.1 프로토콜의 기능을 지원한다.
CacheNegotiatedDocs
지시어는 HTTP/1.0 호환 클라이언트(브라우저 혹은 캐쉬)가
보낸 요청에 대해 협상한 응답을 캐쉬할 수 있게 한다. 이 지시어는
서버나 가상호스트 설정에 사용하며, 아규먼트를 받지않는다.
이 지시어는 HTTP/1.1 클라이언트의 요청과는 관계가 없다.
HTTP/1.1 클라이언트에게 아파치는 응답의 협상 범위를
알려주는 Vary HTTP 응답헤더를 보낸다. 이 정보를
사용하여 다음 요청을 캐쉬된 복사본으로 대체할 수 있는지
판단할 수 있다. 헙상의 범위와 관계없이 캐쉬된 복사본을
권한다면 force-no-vary 환경변수를 설정한다.
내용협상에 대한 다른 정보는 Alan J. Flavell가 쓴 Language Negotiation Notes를 참고하라. 그러나 이 문서는 아직 아파치 2.0의 변화를 반영하지 않을 수 있다.
Apache HTTP Server Version 2.2
웹마스터는 오류나 문제가 발생했을때 아파치의 응답을 설정할 수 있다.
서버가 오류나 문제를 발견했을때 보낼 사용자정의 응답을 정의할 수 있다.
스크립트가 죽은 경우 "500 Server Error" 응답 대신 사용자에게 더 친근한 문구를 사용하거나 다른 (같은 사이트나 외부 사이트의) URL로 리다이렉션을 할 수 있다.
NCSA httpd 1.3은 사용자에게 무의미하고 지루한 오류문을 보냈다. 문제가 발생한 이유를 로그에 남길 수도 없었다.
서버는 다음과 같은 일을 할 수 있다:
다른 사이트의 URL로 리다이렉션하는 것이 유용할 수 있지만, 이 경우 문제를 설명하거나 로그하는데 필요한 정보중 일부만 전달된다.
오류에 대한 정보를 전달하기위해 아파치는 CGI식의 새로운 환경변수를 정의한다:
REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
image/jpeg
REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
9000/712)
REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=ooh.ahhh.com
REDIRECT_SERVER_NAME=crash.bang.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
REDIRECT_URL=/cgi-bin/buggy.pl
REDIRECT_ 접두사에 주목하라.
최소한 REDIRECT_URL과
REDIRECT_QUERY_STRING은 (cgi-script나
cgi-include일) 새 URL로 넘겨진다. 다른 변수는 오류가
발생하기 이전에 (역주; 이름에서 REDIRECT_를
뺀 환경변수가) 존재한 경우에만 있다.
ErrorDocument가
외부로 (같은 서버라도 http:와
같은 스킴(scheme)으로 시작한다면) 리다이렉션한다면
이중 어떤 것도 설정되지 않는다.
AllowOverride가
적절히 설정되었다면 .htaccess 파일에서
ErrorDocument를 사용할
수 있다.
다음은 예이다...
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 http://xxx/
ErrorDocument 404 /Lame_excuses/not_found.html
ErrorDocument 401 /Subscription/how_to_subscribe.html
문법은,
ErrorDocument <3-digit-code> <action>
가능한 action은,
URL로 리다이렉션하는 아파치 행동은 스크립트/server-include에 환경변수를 더 넘겨주도록 변경되었다.
리다이렉션되는 스크립트에 표준 CGI 변수들이 넘어간다. 어디에서 리다이렉션이 일어났는지 알 수 없다.
리다이렉션된 스크립트는 새로운 환경변수들을 사용할
수 있다. 모두 앞에 REDIRECT_가 붙어있다.
REDIRECT_ 환경변수는 원래 CGI 환경변수명
앞에 REDIRECT_를 붙여서 만든다. 예를
들어, HTTP_USER_AGENT는
REDIRECT_HTTP_USER_AGENT가 되었다. 이런 변수에
추가로 스크립트가 원래 URL을 알도록 아파치는
REDIRECT_URL과 REDIRECT_STATUS를
정의한다. 원래 URL과 리다이렉션된 URL 모두 접근 로그에
기록할 수 있다.
ErrorDocument가 같은 서버에 있는 CGI 스크립트로
리다이렉션한다면, 스크립트는 클라이언트에게 오류 상황을
확실히 전달하기위해 출력에 "Status:" 헤더
필드를 포함해야 한다. 예를 들어, Perl로 작성한 ErrorDocument
스크립트는 다음과 같다:
...
print "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...
404 Not Found와 같은 특정 오류
상황에 대한 스크립트라면, 대신 (역주; 고정된)
특정 상태코드와 오류문을 사용할 수 있다.
(클라이언트에게 리다이렉션을 요청하기위해) 응답에
Location: 헤더를 포함한다면, 스크립트는
반드시 (302 Found 같은) 적절한
Status: 헤더를 출력해야 함을 주의하라. 그렇지않으면
Location: 헤더가 아무 소용없게 될 수 있다.
Apache HTTP Server Version 2.2
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:
We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.
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:
SetEnv, which don't really fit well elsewhere.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:
OK.DECLINED. In this case, the server behaves in all
respects as if the handler simply hadn't been there.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.
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 */ };
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.
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 */
};
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:
*.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.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).
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.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.
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).
Stuff that should be discussed here in detail:
ap_auth_type,
ap_auth_name, and ap_requires.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).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).
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.
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).
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".
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_poolpconfptemppchildptransr->poolFor 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.
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).
More text goes here. Describe the 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.
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).
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 DefaultType 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.
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.
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:
(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.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.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.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;
}
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;
}
Apache HTTP Server Version 2.2
The allocation mechanisms within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.
free()d memory and other such
nonsense.The theory is simple. The FILL_BYTE (0xa5)
is written over all malloc'd memory as we receive it, and
is written over everything that we free up during a
clear_pool. We check that blocks on the free list always
have the FILL_BYTE in them, and we check during
palloc() that the bytes still have FILL_BYTE
in them. If you ever see garbage URLs or whatnot containing lots
of 0xa5s then you know something used data that's been
freed or uninitialized.
malloc() and free()d appropriately at the
end.This is intended to be used with something like Electric
Fence or Purify to help detect memory problems. Note that if
you're using efence then you should also add in ALLOC_DEBUG.
But don't add in ALLOC_DEBUG if you're using Purify because
ALLOC_DEBUG would hide all the uninitialized read errors
that Purify can diagnose.
In particular, it causes the table_{set,add,merge}n
routines to check that their arguments are safe for the
apr_table_t they're being placed in. It currently only works
with the unix multiprocess model, but could be extended to others.
This requires a recent gcc which supports
__builtin_return_address(). The error_log output will be a
message such as:
table_push: apr_table_t created by 0x804d874 hit limit of 10
Use l *0x804d874 to find the
source that corresponds to. It indicates that a apr_table_t
allocated by a call at that address has possibly too small an
initial apr_table_t size guess.
This requires a bit of an understanding of how alloc.c
works.
Not all the options outlined above can be activated at the same time. the following table gives more information.
| ALLOC DEBUG | ALLOC USE MALLOC | POOL DEBUG | MAKE TABLE PROFILE | ALLOC STATS | |
|---|---|---|---|---|---|
| ALLOC DEBUG | - | No | Yes | Yes | Yes |
| ALLOC USE MALLOC | No | - | No | No | No |
| POOL DEBUG | Yes | No | - | Yes | Yes |
| MAKE TABLE PROFILE | Yes | No | Yes | - | Yes |
| ALLOC STATS | Yes | No | Yes | Yes | - |
Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.
The various options for debugging memory are now enabled in
the apr_general.h header file in APR. The various options are
enabled by uncommenting the define for the option you wish to
use. The section of the code currently looks like this
(contained in srclib/apr/include/apr_pools.h)
/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/
typedef struct ap_pool_t {
union block_hdr *first;
union block_hdr *last;
struct cleanup *cleanups;
struct process_chain *subprocesses;
struct ap_pool_t *sub_pools;
struct ap_pool_t *sub_next;
struct ap_pool_t *sub_prev;
struct ap_pool_t *parent;
char *free_first_avail;
#ifdef ALLOC_USE_MALLOC
void *allocation_list;
#endif
#ifdef POOL_DEBUG
struct ap_pool_t *joined;
#endif
int (*apr_abort)(int retcode);
struct datastruct *prog_data;
} ap_pool_t;
To enable allocation debugging simply move the #define
ALLOC_DEBUG above the start of the comments block and rebuild
the server.
In order to use the various options the server must be rebuilt after editing the header file.
Apache HTTP Server Version 2.2
Apache 2.0 uses Doxygen to document the APIs and global variables in the the code. This will explain the basics of how to document using Doxygen.
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 > 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" -> "gum"
* "/foo/bar/gum/" -> ""
* "gum" -> "gum"
* "wi\\n32\\stuff" -> "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.
Apache HTTP Server Version 2.2
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.
There are three basic filter types (each of these is actually broken down into two categories, but that comes later).
CONNECTIONAP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)PROTOCOLAP_FTYPE_PROTOCOL,
AP_FTYPE_TRANSCODE)RESOURCEPROTOCOL, 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:
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.
This is actually rather simple in theory, but the code is
complex. First of all, it is important that everybody realize that
there are three filter lists for each request, but they are all
concatenated together. So, the first list is
r->output_filters, then r->proto_output_filters,
and finally r->connection->output_filters. These correspond
to the RESOURCE, PROTOCOL, and
CONNECTION filters respectively. The problem previously, was
that we used a singly linked list to create the filter stack, and we
started from the "correct" location. This means that if I had a
RESOURCE filter on the stack, and I added a
CONNECTION filter, the CONNECTION filter would
be ignored. This should make sense, because we would insert the connection
filter at the top of the c->output_filters list, but the end
of r->output_filters pointed to the filter that used to be
at the front of c->output_filters. This is obviously wrong.
The new insertion code uses a doubly linked list. This has the advantage
that we never lose a filter that has been inserted. Unfortunately, it comes
with a separate set of headaches.
The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.
In the first case, we are creating the subrequest from within a handler
or filter. This means that the next filter should be passed to
make_sub_request function, and the last resource filter in the
sub-request will point to the next filter in the main request. This
makes sense, because the sub-request's data needs to flow through the
same set of filters as the main request. A graphical representation
might help:
Default_handler --> includes_filter --> byterange --> ...
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.
The final topic. :-) Mod_Asis is a bit of a hack, but the
handler needs to remove all filters except for connection filters, and
send the data. If you are using mod_asis, all other
bets are off.
The absolutely last point is that the reason this code was so hard to
get right, was because we had hacked so much to force it to work. I
wrote most of the hacks originally, so I am very much to blame.
However, now that the code is right, I have started to remove some
hacks. Most people should have seen that the reset_filters
and add_required_filters functions are gone. Those inserted
protocol level filters for error conditions, in fact, both functions did
the same thing, one after the other, it was really strange. Because we
don't lose protocol filters for error cases any more, those hacks went away.
The HTTP_HEADER, Content-length, and
Byterange filters are all added in the
insert_filters phase, because if they were added earlier, we
had some interesting interactions. Now, those could all be moved to be
inserted with the HTTP_IN, CORE, and
CORE_IN filters. That would make the code easier to
follow.
Apache HTTP Server Version 2.2
This document is still in development and may be partially out of date.
In general, a hook function is one that Apache 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.
In order to create a new hook, four things need to be done:
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.
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)
...
)
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().
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);
}
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 tradition Apache
hook return 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.
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);
A module that wants a hook to be called needs to do two things.
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;
}
During initialisation, Apache 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 */
};
In the example above, we didn't use the three arguments in
the hook registration function that control calling order.
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. (I spaced
these out so people could do stuff like APR_HOOK_FIRST-2
to get in slightly earlier, but is this wise? - Ben)
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.
Ben Laurie, 15th August 1999
Apache HTTP Server Version 2.2
Many of the documents on these Developer pages are lifted from Apache 1.3's documentation. While they are all being updated to Apache 2.0, they are in different stages of progress. Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.
Apache HTTP Server Version 2.2
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.
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.
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 *papr_pool_t *plogapr_pool_t *ptempserver_rec *sA 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_ttable becomes apr_table_tThe 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_FIRSTHOOK_MIDDLEHOOK_LASTTo 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 it's name
translation, hence the use of the aszPre to define a modifier to the
position HOOK_LAST.
There are now a lot fewer stages to worry about when creating your module definition. The old defintion 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_post_config_init routines get
registeredap_hook_http_methodap_hook_open_logsap_hook_auth_checkerap_hook_access_checkerap_hook_check_user_idap_hook_default_portap_hook_pre_connectionap_hook_process_connectionap_hook_child_initap_hook_create_requestap_hook_fixupsap_hook_handlerap_hook_header_parserpost_read_request for thisap_hook_insert_filterap_hook_log_transactionap_hook_optional_fn_retrieveap_hook_post_read_requestap_hook_quick_handlerap_hook_translate_nameap_hook_type_checkerApache HTTP Server Version 2.2
Warning - this is a first (fast) draft that needs further revision!
Several changes in Apache 2.0 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
Apache 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 Apache 1.3) without introducing fragile or insecure code.
All requests pass through ap_process_request_internal()
in 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 Apache hooks which are irrelevant (and costly in terms of CPU.)
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
reprecussions.
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.
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.
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.
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.
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.
The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.
Needs Documentation. Code is:
switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
if ((access_status = ap_run_access_checker(r)) != 0) {
return decl_die(access_status, "check access", r);
}
if (ap_some_auth_required(r)) {
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
case SATISFY_ANY:
if (((access_status = ap_run_access_checker(r)) != 0)) {
if (!ap_some_auth_required(r)) {
return decl_die(access_status, "check access", r);
}
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
}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.
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.
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.
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.
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.
Apache HTTP Server Version 2.2
When using any of the threaded mpms in Apache 2.0 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 conditons that may only show up in certain conditions under heavy load.
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.
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.
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 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.
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.
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. | |
| cpdflib | ? | ||
| 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://www.mysql.com/doc/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/index.html. |
| libpng | 1.0.x | ? | |
| libpng | 1.2.x | ? | |
| libpq (PostgreSQL) | 7.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. |
Apache HTTP Server Version 2.2
이 문서를 한 문장으로 요약할 수 있다. 아파치가 설정파일을 읽을때 DNS를 의존하지않도록 하라. 아파치가 설정파일을 읽는데 DNS가 필요하다면 서버는 신뢰성 문제 (시작이 안될 수도 있다) 혹은 서비스거부 공격과 (사용자가 다른 사용자에 대한 접근을 가로채는 것을 포함하여) 서비스도둑(theft of service) 공격에 시달릴 수 있다.
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
아파치가 정상적으로 동작하기위해서는 각 가상호스트에
대해 두가지 정보가 절대적으로 필요하다. 이 정보는
ServerName과 서버가
기다리고 응답할 최소 한개의 IP 주소이다. 이 예는 IP 주소가
없기때문에, 아파치는 DNS를 사용하여 www.abc.dom의
주소를 찾아야 한다. 서버가 설정파일을 읽을때 어떤 이유에서건
DNS를 사용할 수 없다면 가상호스트를 만들 수 없다.
이 가상호스트는 요청에 응답할 수 없다. (아파치 1.2 이전
버전에서는 심지어 서버가 부팅도 안한다.)
www.abc.dom의 주소가 10.0.0.1이라고 가정하자.
그리고 다음 설정을 보라:
<VirtualHost 10.0.0.1>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
이제 아파치는 이 가상호스트의 ServerName을
찾기위해 역DNS를 사용해야 한다. 역찾기가 실패하면 아파치는
가상호스트를 부분적으로 끈다. (아파치 1.2 이전 버전에서는
심지어 서버가 부팅도 안한다.) 즉, 이 경우 이름기반
가상호스트라면 가상호스트는 완전히 동작하지않고, ip기반이라면
대부분 동작한다. 그러나 아파치가 서버명을 포함하여 서버의
전체 URL을 만들어야 한다면 정상적인 URL을 만들지 못한다.
아래 경우 이 두가지 문제가 없다.
<VirtualHost 10.0.0.1>
ServerName www.abc.dom
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
(최소한) 두가지 종류의 서비스거부가 발생할 수 있다.
아파치 1.2 이전 버전의 경우 어떤 가상호스트에서라도
위에서 말한 두 DNS 검색이 실패하면 서버가 켜지지도 않는다.
DNS가 당신의 권한 밖의 문제일 수도 있다. 예를 들어,
abc.dom이 고객 사이트이고 고객이 자신의 DNS를
관리한다면, www.abc.dom 레코드를 지우기만 해도
(1.2 이전) 서버는 시작하지 못한다.
훨씬 더 교활한 방법도 있다. 다음 설정을 살펴보자:
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
<VirtualHost www.def.dom>
ServerAdmin webguy@def.dom
DocumentRoot /www/def
</VirtualHost>
당신이 www.abc.dom에 10.0.0.1,
www.def.dom에 10.0.0.2를 할당했다고 하자.
또, def.dom은 자체 DNS를 사용한다고 가정하자.
이 설정과 함께 def.dom을 abc.dom으로
가는 모든 통신을 가로챌 수 있는 장소에 두었다. 그렇다면 그들은
www.def.dom을 10.0.0.1로 설정하기만 하면 된다.
그들이 자체 DNS를 사용하기때문에 당신은 그들이 원하는데로
www.def.dom 레코드를 설정하는 것을 막을 수
없다.
(사용자가 http://www.abc.dom/whatever 형식의
URL을 입력하는 경우를 포함하여) 10.0.0.1로 오는 모든 요청을
def.dom 가상호스트가 서비스하게 된다. 왜 이런
일이 일어나는지 이해하려면 아파치가 어떻게 가상호스트로
오는 요청을 처리하는지에 대한 설명이 필요하다.
여기에 대강 설명되있다.
아파치 1.1에서 이름기반
가상호스트 지원이 포함되었기때문에 아파치는 웹서버를
실행하는 호스트의 IP 주소(들)를 알 필요가 생겼다. 이 주소는
(있다면) 전역 ServerName
혹은 C 함수 gethostname으로 (명령프롬프트에
"hostname"을 입력했을때와 같은 결과) 얻는다. 그러면 이 주소로
DNS 검색을 한다. 현재 이 검색은 피할 수 없다.
DNS 서버가 죽어서 이 검색이 실패할 것 같다면
/etc/hosts에 호스트명을 집어넣을 수 있다.
(컴퓨터가 정상적으로 부팅되었다면 아마 이미 들어있을 것이다.)
그리고 DNS가 실패하면 서버가 /etc/hosts를
사용하는지 확인하라. 사용하는 운영체제에 따라
/etc/resolv.conf 혹은 /etc/nsswitch.conf를
수정하면 될 것이다.
서버가 어떤 이유에서건 DNS를 검색하면 안된다면
HOSTRESORDER 환경변수를 "local"로 설정하고
아파치를 실행할 수 있다. mod_env를
사용하여 환경을 변경하지 않는다면 이 환경변수는
CGI에도 영향을 준다. 운영체제의 manpage나 FAQ를 참고하는
것이 좋다.
VirtualHost에 IP
주소를 사용하라
Listen에
IP 주소를 사용하라
ServerName을
가지게 하라
<VirtualHost _default_:*> 서버를
만들어라DNS와 관련된 상황은 매우 바람직하지 못하다. 아파치 1.2에서 우리는 DNS가 실패한 경우에도 최소한 서버가 켜지도록 노력했지만 결과는 나빴다. 어쨌든 설정파일에 직접 IP 주소를 요구하는 것은 번호를 다시 설정해야할 요즘 인터넷에 매우 바람직하지 못하다.
위에서 설명한 서비스도둑 공격을 막는 한가지 방법은 검색한 IP 주소에 다시 역DNS 검색을 하여 두 이름을 비교하는 것이다. 서로 다른 경우 가상호스트를 가동하지 않을 수 있다. 이 방법은 역DNS가 올바로 설정되야 한다. (FTP 서버나 TCP wrapper가 "중복-역" DNS 검색을 자주 사용하기때문에 대부분의 관리자에게 익숙할 것이다.)
어쨌든 IP 주소를 사용하지않으면 DNS가 실패한 경우 가상호스트 웹서버를 믿을 수 있게 시작할 수 없다. 설정의 일부를 무시하는 것과 같은 부분적인 해결책은 웹서버 전체를 시작하지않는 것보다 더 나쁠 수도 있다.
HTTP/1.1이 나왔고 브라우저와 프록시가 Host
헤더를 보내기 시작했으므로 IP기반 가상호스트를 완전히
사용하지않는 것이 가능해질 것이다. 그러면 웹서버는 설정중에서
DNS 검색을 할 필요가 없어진다. 그러나 1997년 3월에는 중요한
웹서버에 포함할 정도로 이름기반 가상호스트가 널리 사용되지
않았다.
Apache HTTP Server Version 2.2
아파치 웹서버는 관리자가 모듈들을 선택하여 서버에 포함할
기능을 결정할 수 있는 모듈화된 프로그램이다. 서버를 컴파할때
httpd 실행파일에 정적으로 모듈을 컴파일할
수 있다. 아니면 모듈을 httpd 실행파일과
분리하여 동적공유객체(Dynamic Shared Objects, DSO)로 컴파일할
수 있다. DSO 모듈은 서버를 컴파일할때 컴파일하거나, Apache
Extension Tool (apxs)을
사용하여 나중에 컴파일하여 추가할 수 있다.
이 문서는 DSO 모듈 사용법과 배경 이론을 설명한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
아파치 핵심에 정적으로 컴파일해야할
mod_so.c라는 모듈은 아파치 모듈을
읽어들이기위한 DSO를 지원한다.
이 모듈은 core를 제외하고 DSO가
될 수 없는 유일한 모듈이다. 실제로 다른 모든 아파치 모듈은
설치 문서에서 설명한
configure의 --enable-module=shared
옵션을 사용하여 DSO로 컴파일할 수 있다. 모듈을
mod_foo.so와 같이 DSO로 컴파일한후 httpd.conf
파일에 mod_so의
LoadModule 명령어를
사용하여 서버 시작시 혹은 재시작시 그 모듈을 읽어들일 수
있다.
아파치 모듈(특히 제삼자가 만든 모듈)로 사용할 DSO 파일을 쉽게
만들기위해 apxs (APache
eXtenSion)라는 새로운 지원 프로그램이 있다. 이 프로그램은
아파치 소스 트리 밖에서 DSO로 사용할 모듈을
컴파일할때 사용한다. 개념은 쉽다. 아파치를 설치할때
configure와 make install이
아파치 C 헤더파일을 설치하고, DSO 파일을 컴파일하기위한
플래폼 특유의 컴파일러 옵션과 링커 옵션을 apxs
프로그램에 기록한다. 그래서 apxs를 사용하는 사용자는
아파치 배포본 소스 트리없이, 또 DSO 지원을 위한 플래폼 특유의
컴파일러 옵션와 링커 옵션에 신경을 쓰지않고 자신의 아파치
모듈 소스를 컴파일할 수 있다.
Apache 2.0의 DSO 기능에 대한 짧고 간략한 요약이다:
mod_foo.c를 DSO
mod_foo.so로:
$ ./configure --prefix=/path/to/install --enable-foo=shared
$ make install
mod_foo.c를 DSO
mod_foo.so로:
$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c --enable-foo=shared
$ make install
$ ./configure --enable-so
$ make install
mod_foo.c를
DSO mod_foo.so로:
$ cd /path/to/3rdparty
$ apxs -c mod_foo.c
$ apxs -i -a -n foo mod_foo.la
모든 경우 일단 공유 모듈이 컴파일되면, httpd.conf에
LoadModule 지시어를
사용하여 아파치가 그 모듈을 읽어들이게 만든다.
현대적인 유닉스류에는 동적공유객체 (DSO)의 동적 링킹/로딩(dynamic linking/loading)이라고 하여, 특별한 형식의 실행코드 조각을 만들어 실행중인 실행프로그램의 주소공간에 읽어들이는 멋진 기능이 있다.
보통 두가지 방법으로 읽어들일 수 있다. 하나는 실행프로그램이
시작할때 ld.so라는 시스템 프로그램이 자동으로
읽어들이는 경우고, 다른 하나는 실행중인 프로그램이
dlopen()/dlsym() 시스템호출로 유닉스 로더(loader)의
시스템 인터페이스을 사용하여 직접 읽어들이는 경우다.
첫번째 경우 DSO를 보통 공유라이브러리(shared libraries)
혹은 DSO 라이브러리라고 부르며, 파일은
libfoo.so나 libfoo.so.1.2 같은
이름을 가진다. 이들은 시스템 디렉토리(보통 /usr/lib)에
있고, 컴파일시 링커 명령어에 -lfoo를 주어
실행파일과 연결한다. 이렇게 직접 써준 라이브러리는 실행파일에
참조되여서, 프로그램이 시작할때 링커 옵션 -R로
직접 지정한 경로, 환경변수 LD_LIBRARY_PATH로
지정한 경로 혹은 /usr/lib에서 유닉스 로더가
libfoo.so를 찾을 수 있다. 그러면 실행프로그램의
(아직 못찾은(unresolved)) 심볼(symbol)을 DSO에서 찾게된다.
DSO는 보통 실행프로그램의 심볼을 찾지않기 때문에 (DSO가
재사용가능한 일반적인 코드 라이브러리이므로) 찾기는 여기서
끝난다. 유닉스 로더가 심볼 찾기를 완전히 담당하므로 실행프로그램이
직접 DSO에서 심볼을 찾을 필요가 없다. (사실 ld.so를
부르는 코드는 정적이 아닌 모든 실행프로그램에 링크되는 실행시
시작코드의 일부다.) 공통된 라이브러리 코드를 동적으로 읽어들이는
장점은 명확하다. 라이브러리 코드가 모든 프로그램에 중복해서
저장되는 대신 libc.so와 같은 시스템 라이브러리에
한번만 저장되기 때문에 디스크 공간이 절약된다.
두번째 경우 DSO를 보통 공유객체(shared objects)
혹은 DSO 파일이라고 부르고, (규칙상 이름은
foo.so이지만) 파일의 확장자는 자유롭다. 이
파일들은 보통 프로그램 자체 디렉토리에 위치하고 실행프로그램에
자동으로 연결되지 않는다. 대신 실행프로그램은 실행시
dlopen()을 사용하여 DSO를 주소공간에
직접 읽어들여야 한다. 이때 실행프로그램은 DSO에서 심볼을
찾지 않는다. 대신 앞에서 본 유닉스 로더는 자동으로 실행파일과
실행파일이 이미 읽어들인 DSO 라이브러리(특히 항상 존재하는
libc.so의 모든 심볼)에서 DSO의 (아직 못찾은)
심볼을 찾는다. 그래서 DSO는 마치 처음부터 실행프로그램에
정적으로 링크된것과 같이 실행파일의 심볼을 알게된다.
DSO의 API를 이용하기위해서 마지막으로 실행프로그램은
dlsym()으로 DSO에서 특정 심볼을 찾아서, 앞으로
사용하기위해 디스패치(dispatch) 표 등에 저장한다.
다른 말로 실행프로그램은 사용할 모든 실볼을 직접 찾아야한다.
이런 구조의 장점은 프로그램의 일부를 프로그램이
필요할때까지 읽어들이지 않아도 (그래서 메모리를 낭비하지
않게) 된다는 점이다. 기본 프로그램의 기능을 확장하기위해
필요한 경우 이 부분을 동적으로 읽어들일 수 있다.
이런 DSO 구조가 자연스럽게 보이지만, 최소한 어려운 점이 한가지있다. 프로그램을 확장하기위해 DSO를 사용할때 DSO가 실행프로그램의 심볼을 찾는 일이다. 왜? DSO가 실행프로그램의 심볼을 "역으로 찾는 것"은 (라이브러리는 자신을 사용하는 프로그램에 대해 모른다는) 라이브러리 설계에 반하며, 모든 플래폼에서 지원되지않고 표준화되지도 않았기 때문이다. 실제로 실행파일의 전역심볼(global symbol)은 보통 익스포트(export)되지 않기때문에 DSO가 사용할 수 없다. DSO를 사용하여 실행중 프로그램을 확장하려면 링커에게 모든 전역심볼을 익스포트하도록 강제하는 것이 주된 해결책이다.
공유라이브러리는 DSO 방식의 설계원칙대로 전형적이기때문에 운영체제가 제공하는 거의 모든 종류의 라이브러리가 사용한다. 반대로 많은 프로그램은 프로그램을 확장하기위해 공유객체를 사용하지 않는다.
1998년 실행중 실제로 기능을 확장하기위해 DSO 구조를 사용한 소프트웨어 패키지는 (XS 구조와 DynaLoader 모듈을 사용한) Perl 5, Netscape Server 등으로 드물었다. 아파치는 이미 기능을 확장하기위해 모듈 개념을 사용했고 외부 모듈을 아파치 핵심기능에 연결하기위해 내부적으로 디스패치목록을 이용한 접근방법을 사용했기때문에 1.3 버전부터 이 대열에 합류했다. 그래서 아파치는 실행중 모듈을 읽어들이는데 DSO를 사용하도록 운명지워졌다.
앞에서 말한 DSO를 사용하면 다음과 같은 장점이 있다:
configure
옵션대신 httpd.conf의 LoadModule을 사용하여 실행중에
결합되므로 서버 패키지 실행이 더 유연하다. 예를 들어 한번의
아파치 설치만으로 다른 서버(표준 버전과 SSL 버전, 최소화
버전과 기능추가 버전 [mod_perl, PHP3] 등)를 실행할
수 있다.apxs를 가지고 아파치 소스 트리 밖에서
작업하고 apxs -i와 apachectl restart
명령어만으로 현재 개발한 모듈의 새 버전을 실행중인 아파치
서버에 반영할 수 있어서 더 쉽게 아파치 모듈을 개발할 수
있다.DSO는 다음과 같은 단점이 있다:
ld -lfoo)에
링크할 수 없는 플래폼이 있기때문에 (예를 들어 ELF기반
플래폼은 지원하지만 a.out기반 플래폼은 보통 이 기능을
지원하지 않는다) 모든 종류의 모듈에 DSO를 사용할 수 없다.
다른 말로 DSO 파일로 컴파일하는 모듈은 아파치 핵심과 아파치
핵심이 사용하는 C 라이브러리(libc)와 다른
동적/정적 라이브러리, 위치독립코드를 담고 있는 정적 라이브러리
아카이브(libfoo.a)의 심볼만을 사용할 수 있다.
다른 코드를 사용하려면 아파치 핵심이 그것을 참조하던지,
dlopen()으로 직접 코드를 읽어들여야 한다.Apache HTTP Server Version 2.2
아파치 웹서버는 환경변수(environment variable)라는 변수에 정보를 저장할 수 있다. 이 정보를 사용하여 로그나 접근제어 등 여러 작업을 조절한다. 또, 환경변수는 CGI 스크립트와 같은 외부 프로그램과 통신하는 수단이 된다. 이 문서는 환경변수를 다루고 사용하는 다양한 방법들을 설명한다.
이 변수들을 환경변수라고 부르지만, 운영체제에서 말하는 환경변수와 다르다. 이 변수는 아파치 내부에 저장되고 사용된다. 환경변수는 CGI 스크립트나 Server Side Include 스크립트로 넘겨질때만 실제 운영체제 환경변수가 된다. 서버를 실행하는 운영체제 환경을 수정하고 싶다면 운영체제 쉘에서 환경을 수정해야 한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
아파치에서 환경변수를 설정하는 가장 기본적인 방법은
무조건적인 SetEnv 지시어를 사용하는 것이다. PassEnv 지시어를 사용하여
서버를 시작한 쉘에서 환경변수를 가져올 수도 있다.
더 유연하게, mod_setenvif가 제공하는 지시어는 요청마다
요청의 특징에 따라 환경변수를 설정한다. 예를 들어, 특정
브라우저로 (User-Agent) 요청하거나 특정 Referer (맞춤법이
틀리지 않았다) 헤더가 있는 경우에만 변수를 설정할 수
있다. 심지어 mod_rewrite에 있는 RewriteRule의
[E=...] 옵션을 사용하여 더 유연하게 환경변수를
설정할 수도 있다.
마지막으로 mod_unique_id는 각 요청에 대해 어떤 경우에도
"모든" 요청중에 확실히 유일한(겹치지않은) 값으로
UNIQUE_ID 환경변수를 설정한다.
CGI 스크립트와 SSI 문서는 아파치 설정에서 설정하였거나 쉘에서 가져온 환경변수 외에 추가로 CGI 규약이 규정한 요청에 대한 정보를 알려주는 환경변수들을 받는다.
suexec.c에 정의된다.| 관련된 모듈 | 관련된 지시어 |
|---|---|
환경변수의 주된 용도중 하나는 CGI 스크립트와 정보를 교환하는 것이다. 앞에서 설명했듯이 아파치 설정에서 설정한 변수외에 요청에 대한 표준 정보를 가진 변수가 CGI 스크립트로 넘어간다. 더 자세한 내용은 CGI 투토리얼을 참고하라.
mod_include의 INCLUDES 필터가 처리하는
서버파싱 (SSI) 문서는 echo 요소를 사용하여
환경변수를 출력할 수 있고, 환경변수를 사용하여 요청의
특징에 따라 흐름제어 요소로 페이지의 일부를 변경할 수
있다. 아파치는 또 SSI 문서에게 위에서 설명한 표준 CGI
환경변수를 제공한다. 더 자세한 내용은 SSI 투토리얼을 참고하라.
allow from env=과 deny from env=
지시어를 사용하여 환경변수 값에 따라 서버로의 접근을
조절할 수 있다. SetEnvIf와 같이 사용하면
클라이언트의 특징에 따라 자유롭게 서버로의 접근을 제어할
수 있다. 예를 들어, 특정 브라우저의 (User-Agent) 접근을
거부할 수 있다.
LogFormat의
%e 옵션을 사용하여 환경변수를 접근 로그에
기록할 수 있다. 또, CustomLog 지시어의
조건부 형식을 사용하면 환경변수의 상황에 따라 요청을
로그할지 여부를 결정할 수 있다. SetEnvIf와 같이 사용하여
어떤 요청을 로그할지 자유롭게 결정할 수 있다. 예를 들어,
파일명이 gif로 끝나는 요청은 로그하지 않거나,
외부 네트웍에 있는 클라이언트의 요청만을 로그할 수 있다.
Header
지시어는 클라이언트에게 응답을 보낼때 환경변수의 유무에
따라 어떤 HTTP 헤더를 포함할지 결정할 수 있다. 예를
들어, 클라이언트의 요청에 특정 헤더가 있는 경우에만
어떤 응답 헤더를 보낼 수 있다.
mod_ext_filter의 ExtFilterDefine
지시어로 설정한 외부 필터를 disableenv=와
enableenv= 옵션을 사용하여 환경변수에 따라
선택적으로 실행할 수 있다.
RewriteCond의
TestString에 %{ENV:...} 형식을
사용하면 mod_rewrite의 재작성 엔진이 환경변수에 따라
다르게 행동한다. mod_rewrite에서 앞에 ENV:를
붙이지않고 접근하는 변수는 실제 환경변수가 아님을 주의하라.
그들은 다른 모듈에서 읽을 수 없는 mod_rewrite에 한정된
변수다.
클라이언트와 원활한 동작하기위해 아파치는 특별한
클라이언트에 대해 자신의 행동을 수정한다. 보통 BrowserMatch에서
환경변수를 정의하여 이런 문제를 해결한다. 그러나 SetEnv와 PassEnv로도 가능하다.
요청이 이후 버전을 사용하더라도 HTTP/1.0 요청으로 처리한다.
DEFLATE 필터를 사용할때 이 환경변수는
브라우저의 accept-encoding 설정을 무시하고 무조건
압축된 결과를 보낸다.
응답을 클라이언트에게 보내기 전에 응답 헤더에서
Vary 필드를 뺀다. 어떤 클라이언트는 이
필드를 제대로 해석하지 못한다. 이 변수는 이런 문제를
해결한다. 또한, 이 변수는
force-response-1.0을 가정한다.
HTTP/1.0 요청을 하는 클라이언트에게 HTTP/1.0 응답을 강제한다. 원래 AOL 프록시에 문제가 있어서 만들어졌다. 어떤 HTTP/1.0 클라이언트는 HTTP/1.1 응답을 받으면 제대로 동작하지 않으므로, 이 문제를 해결하기위해 사용한다.
값이 "1"이면 text/html이 아닌 content-type에
대해 mod_deflate의 DEFLATE 출력필터를
사용하지 않는다. (gzip 뿐만 아니라 "identity"가 아닌 모든
인코딩의) 정적으로 압축한 파일의 경우에도
mod_negotiation은 이 변수를 참고한다.
이 옵션을 설정하면 mod_deflate의
DEFLATE 필터를 사용하지 않고,
mod_negotiation은 인코딩된 자원을
보내지 않는다.
KeepAlive를
무시한다.
이 변수는 mod_negotiation의 행동에
영향을 미친다. 변수가 (en, ja,
x-klingon 등) 언어태그를 담고있다면,
mod_negotiation는 그 언어로 된 변형을
보내길 시도한다. 그런 변형이 없다면 일반적인 협상 과정을 시작한다.
서버가 더 조심히 클라이언트에게 리다이렉션을 보낸다. 보통 리다이렉션을 처리하는데 문제가 있는 클라이언트을 위해 사용한다. 원래 Microsoft의 WebFolders 소프트웨어가 DAV 메써드를 통해 디렉토리 자원의 리다이렉션을 처리하는데 문제가 있어서 만들어졌다.
2.0.40 이후 버전에 있다
아파치가 클라이언트의 요청에 대한 응답으로 리다이렉션을 보낼때 클라이언트가 자동으로 리다이렉션을 따라가지 못하는(혹은 않는) 경우에 대비하여 응답에 사용자에게 보여줄 문구를 포함한다. 아파치는 보통 이 글을 아파치가 사용하는 문자집합인 ISO-8859-1로 표시한다.
그러나 리다이렉션된 페이지가 다른 문자집합을 사용할 경우 어떤 이상한 브라우저 버전은 실제 페이지가 아니라 리다이렉션 페이지의 문자집합을 사용하려고 한다. 예를 들어, 그리스어가 이상하게 보일 수 있다.
이 환경변수는 아파치가 리다이렉션 페이지에 문자집합을 설정하지않도록 하여, 이런 브라우저가 실제 페이지의 문자집합을 올바로 사용하게 만든다.
클라이언트들의 이미 알려진 문제를 해결하기위해 httpd.conf에 다음 내용을 포함하길 바란다.
# # 다음 지시어들은 일반적인 HTTP 응답을 변경한다. # 첫번째 지시어는 Netscape 2.x와 이를 가장한 브라우저에게 # keepalive를 사용하지 않는다. 이들 브라우저 구현에 문제가 있다. # 두번째 지시어는 HTTP/1.1 구현이 잘못되었고 301이나 302 # (리다이렉션) 응답에 사용한 keepalive를 제대로 지원하지 # 못하는 Microsoft Internet Explorer 4.0b2를 위한 것이다. # BrowserMatch "Mozilla/2" nokeepalive BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 # # 다음 지시어는 기본적인 HTTP/1.1 응답을 이해하지 못하여 # HTTP/1.0 규약을 어기는 브라우저에게 HTTP/1.1 응답을 보내지 않는다. # BrowserMatch "RealPlayer 4\.0" force-response-1.0 BrowserMatch "Java/1\.0" force-response-1.0 BrowserMatch "JDK/1\.0" force-response-1.0
이 예제는 이미지에 대한 요청을 접근 로그에 기록하지 않는다. 특정 디렉토리에 대한 혹은 특정 호스트에서 온 요청을 로그하지 않도록 쉽게 수정할 수 있다.
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
이 예는 현재 서버외의 사용자가 페이지에 서버에 있는 이미지를 포함하지 못하도록 하는 방법을 설명한다. 이 설정을 권장하지는 않으며, 제한된 경우에만 동작한다. 우리는 모든 이미지가 /web/images 디렉토리 안에 있다고 가정한다.
SetEnvIf Referer "^http://www.example.com/" local_referal # Referer 정보를 보내지 않는 브라우저를 허용한다 SetEnvIf Referer "^$" local_referal <Directory /web/images> Order Deny,Allow Deny from all Allow from env=local_referal </Directory>
이 기법에 대한 자세한 설명은 ApacheToday 투토리얼 " Keeping Your Images from Adorning Other Sites"를 참고하라.
Apache HTTP Server Version 2.2
FAQ 최신판은 아파치 웹사이트 <http://httpd.apache.org/docs/2.2/faq/>에서 볼 수 있다.
아파치 2.0이 나온지 얼마 안되서 우리는 아직 자주 물어보는 질문 (FAQ)이 무엇인지 모른다. 내용이 채워질 때까지 여기에 해답이 없다면 아파치 1.3 FAQ도 참고하라.
아파치 서버 소프트웨어에 문제가 생기면 다음과 같은 단계를 따른다:
/usr/local/apache2/logs/error_log이지만,
정확한 위치는 설정파일의 ErrorLog 지시어를 참고하라.아파치에 대한 지식을 공유하길 원하는 활발한 사용자 공동체들이 있다. 일반적으로 이런 공동체에 참여하는 것이 문제의 답을 얻는 가장 좋고 빠른 방법이다.
USENET 뉴스그룹:
위의 단계를 모두 시도하고도 해결책이 없다면, 버그를 보고하여 웹서버 개발자들에게 문제를 알리길 바란다.
core dump를 만들며 서버가 죽는 경우라면 (가능하면) backtrace(역주; 문제가 실행파일의 정확히 어떤 지점에서 발생하였고, 프로그램이 그 지점까지 어떤 경로로 실행되었는지를 알려주는 정보)를 포함하길 바란다. 예를 들어,
# cd ServerRoot
# dbx httpd core
(dbx) where
(ServerRoot, httpd, core
파일의 실제 위치를 대신 사용하라. dbx 대신
gdb를 사용해야 할 수도 있다.)
40명 가량의 자발적으로 참여한 개발자만으로는 수백만의 사용자에게 아파치에 대해 일일이 지원할 수 없다. 무료 지원을 얻으려면 사용자 공간에 참여하길 권한다.
아파치에 대한 직업적인 유료 지원은 여러 회사에서 제공한다.
플래폼이 sendfile 시스템호출을 지원한다면,
아파치는 응답의 속도를 빠르게하기위해 이 시스템호출을 사용한다.
불행히도 어떤 시스템에서 아파치는 컴파일할때
sendfile이 정상적으로 작동하지 않는데도 정상적으로
작동한다고 오판한다. 이 문제는 네트웍 파일시스템이나 비표준
파일시스템을 사용할때 자주 발생한다.
이 문제의 증상은 오류 로그(error log)에 위의 문구를
기록하거나 크기가 0이 아닌 파일에 대해 크기가 0인 응답을
하는 경우이다. 동적으로 내용을 생성할때는
sendfile을 사용하지 않기때문에 일반적으로 정적인
파일을 요청할때만 문제가 발생한다.
문제를 해결하려면 서버가 sendfile을 사용하지
않도록 EnableSendfile
지시어를 사용한다. 또, 이와 유사한 문제에 대해 EnableMMAP을 참고하라.
win32에서 AcceptEx 시스템호출에 대한 오류문을
나오면, Win32DisableAcceptEx
지시어를 참고하라.
보통 CGI 스크립트에 문제가 있으면 브라우저에게 Internal
Server Error를 보내고 오류로그에 이 문구를 기록한다.
이런 문제를 디버깅할때 CGI 투토리얼이
도움이 될 수 있다.
Apache HTTP Server Version 2.2
The Apache Software Foundation (ASF) is a 501(c)3 non-profit organization providing support for the Apache community of open-sourced software projects. For more details, please see the Apache Software Foundation FAQ
The Apache HTTP Server -- sometimes called Apache httpd -- is a project of the Apache Software foundation aimed at creating a robust, commercial-grade, featureful, and freely-available source code implementation of an HTTP (Web) server. For more information, please see the About Apache page.
Apache is run on millions of Internet servers. It has been tested thoroughly by both developers and users. The Apache HTTP Server Project maintains rigorous standards before releasing new versions of our server, and our server runs without a hitch on over 70% of all WWW servers available on the Internet. When bugs do show up, we release patches and new versions as soon as they are available.
You may NOT use any original artwork from the Apache Software Foundation, nor make or use modified versions of such artwork, except under the following conditions:
Apache HTTP Server Version 2.2
플래폼이 sendfile 시스템호출을 지원한다면,
아파치는 응답의 속도를 빠르게하기위해 이 시스템호출을 사용한다.
불행히도 어떤 시스템에서 아파치는 컴파일할때
sendfile이 정상적으로 작동하지 않는데도 정상적으로
작동한다고 오판한다. 이 문제는 네트웍 파일시스템이나 비표준
파일시스템을 사용할때 자주 발생한다.
이 문제의 증상은 오류 로그(error log)에 위의 문구를
기록하거나 크기가 0이 아닌 파일에 대해 크기가 0인 응답을
하는 경우이다. 동적으로 내용을 생성할때는
sendfile을 사용하지 않기때문에 일반적으로 정적인
파일을 요청할때만 문제가 발생한다.
문제를 해결하려면 서버가 sendfile을 사용하지
않도록 EnableSendfile
지시어를 사용한다. 또, 이와 유사한 문제에 대해 EnableMMAP을 참고하라.
win32에서 AcceptEx 시스템호출에 대한 오류문을
나오면, Win32DisableAcceptEx
지시어를 참고하라.
보통 CGI 스크립트에 문제가 있으면 브라우저에게 Internal
Server Error를 보내고 오류로그에 이 문구를 기록한다.
이런 문제를 디버깅할때 CGI 투토리얼이
도움이 될 수 있다.
Apache HTTP Server Version 2.2
FAQ 최신판은 아파치 웹사이트 <http://httpd.apache.org/docs/2.2/faq/>에서 볼 수 있다. 또, 검색하고 출력하기 편하게 FAQ를 한 페이지로 볼 수 있다.
아파치 2.0이 나온지 얼마 안되서 우리는 아직 자주 물어보는 질문 (FAQ)이 무엇인지 모른다. 내용이 채워질 때까지 여기에 해답이 없다면 아파치 1.3 FAQ도 참고하라.
Apache HTTP Server Version 2.2
아파치 서버 소프트웨어에 문제가 생기면 다음과 같은 단계를 따른다:
/usr/local/apache2/logs/error_log이지만,
정확한 위치는 설정파일의 ErrorLog 지시어를 참고하라.아파치에 대한 지식을 공유하길 원하는 활발한 사용자 공동체들이 있다. 일반적으로 이런 공동체에 참여하는 것이 문제의 답을 얻는 가장 좋고 빠른 방법이다.
USENET 뉴스그룹:
위의 단계를 모두 시도하고도 해결책이 없다면, 버그를 보고하여 웹서버 개발자들에게 문제를 알리길 바란다.
core dump를 만들며 서버가 죽는 경우라면 (가능하면) backtrace(역주; 문제가 실행파일의 정확히 어떤 지점에서 발생하였고, 프로그램이 그 지점까지 어떤 경로로 실행되었는지를 알려주는 정보)를 포함하길 바란다. 예를 들어,
# cd ServerRoot
# dbx httpd core
(dbx) where
(ServerRoot, httpd, core
파일의 실제 위치를 대신 사용하라. dbx 대신
gdb를 사용해야 할 수도 있다.)
40명 가량의 자발적으로 참여한 개발자만으로는 수백만의 사용자에게 아파치에 대해 일일이 지원할 수 없다. 무료 지원을 얻으려면 사용자 공간에 참여하길 권한다.
아파치에 대한 직업적인 유료 지원은 여러 회사에서 제공한다.
Apache HTTP Server Version 2.2
이 문서는 아파치에서 필터를 사용하는 방법을 설명한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
필터(filter)는 서버가 보내거나 받는 자료에 적용되는 작업이다. 클라이언트가 서버에게 보내는 자료는 입력필터(input filter)가 처리하고, 서버가 클라이언트에게 보내는 자료는 출력필터(output filter)가 처리한다. 자료에 여러 필터를 사용할 수 있고, 직접 필터의 순서를 지정할 수 있다.
아파치는 이어받기(byte-range) 요청 등을 처리하기위해
내부적으로 필터를 사용한다. 또, 설정 지시어를
사용하여 선택가능한 필터를 제공하는 모듈도 있다.
SetInputFilter,
SetOutputFilter,
AddInputFilter,
AddOutputFilter,
RemoveInputFilter,
RemoveOutputFilter
지시어로 자료를 처리하는 필터를 조절한다.
현재 아파치 웹서버 배포본은 사용자가 선택할 수 있는 다음과 같은 필터를 제공한다.
mod_include가 처리하는 Server-Side Includesmod_deflate를 사용하여 출력을
클라이언트로 보내기 전에 압축
또, mod_ext_filter 모듈을 사용하여
외부 프로그램을 필터로 사용할 수도 있다.
Apache HTTP Server Version 2.2
이 문서는 웹 서비스 일반에 대한, 특히 아파치와 관련된, 용어들을 정의한다. 각 개념에 대한 자세한 정보는 링크를 참고하라. (역주; 현재 단어의 순서는 한글 순서가 아니라, 영문자 순서입니다. 용어번역표는 여기를 참고하길 바랍니다.)
INCLUDES 출력필터는 문서의 Server
Side Includes를 처리한다.www가 호스트명이고
example.com이 도메인명일때,
www.example.com은 완전한 도메인명이다.cgi-script
핸들러는 CGI로 처리할 파일을 지정한다./usr/local/apache2/conf/httpd.conf이지만, 실행할때
혹은 컴파일때 설정으로 변경할 수 있다.GET,
POST, PUT 등이 있다.text/html, image/gif,
application/octet-stream 등이다. MIME-type은 HTTP의
Content-Type 헤더 (header)로
전송한다./images/.*(jpg|gif)$"로 지칭할 수
있다. 아파치는 PCRE 라이브러리를
사용하여 Perl호환 정규표현식을 지원한다.tar 도구를 사용하여 파일들을 모은 묶음. 아파치는
tar 파일을 압축하거나 pkzip으로 압축하여 배포된다.http나 https같은 스킴(scheme), 호스트명,
경로로 구성된다. 이 페이지의 URL은
http://httpd.apache.org/docs/2.2/glossary.html이다.Apache HTTP Server Version 2.2
이 문서는 아파치에서 핸들러를 사용하는 방법을 설명한다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
파일을 요청할때 아파치가 내부적으로 수행할 작업을 "핸들러(handler)"라고 한다. 일반적으로 파일은 파일 종류에 따라 암묵적인 핸들러를 가지고 있다. 모든 파일은 보통 간단히 서버가 서비스하지만, 어떤 파일 종류는 따로 "처리된다(handled)".
Apache 1.1부터 핸들러를 명시적으로 사용할 수 있게 되었다. 파일 종류와 관계없이 핸들러를 파일의 확장자나 위치에 따라 지정할 수 있다. 이는 더 훌륭한 방법이고 파일을 종류와 핸들러 둘 모두와 연계할 수 있기때문에 좋다. (여러 확장자를 가진 파일도 참고)
핸들러는 서버나 모듈로 구현하여, Action 지시어로 추가할
수 있다. 표준 배포본에 있는 기본 핸들러는 다음과 같다:
default_handler()를 사용하여 파일을 보낸다.
(core)mod_asis)mod_cgi)mod_imagemap)mod_info)mod_status)mod_negotiation)다음 지시어는 확장자가 html인 파일을
요청할 경우 footer.pl CGI 스크립트를 띄운다.
Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html
CGI 스크립트는
(PATH_TRANSLATED 환경변수가 지칭하는) 원래
요청한 문서를 적절히 수정한 후 보낸다.
다음 지시어는 HTTP 헤더를 포함하는 파일에
send-as-is 핸들러를 지시한다.
/web/htdocs/asis/ 디렉토리 안에 있는 모든
파일은 확장자와 관계없이 send-as-is 핸들러가
처리한다.
<Directory /web/htdocs/asis>
SetHandler send-as-is
</Directory>
핸들러 기능을 구현하기위해 사용함직한
Apache API가 추가되었다.
특히 request_rec 구조체에 새로운 필드가
추가되었다:
char *handler
모듈이 핸들러를 사용하려면, 요청의
invoke_handler 단계 이전에
r->handler에 핸들러 이름을 지정해주기만
하면 된다. 핸들러는 content type 대신 핸들러 이름을 사용한
것을 제외하고는 전과 같이 구현되었다. 꼭 지킬 필요는 없지만
핸들러 이름에 슬래쉬를 사용하지 않고, 단어들 사이에 빼기
기호를 사용하는 것이 일반적이다. 그래서 핸들러 이름이
media type과 겹치지 않는다.
Apache HTTP Server Version 2.2
Access control refers to any means of controlling access to any resource. This is separate from authentication and authorization.
Access control can be done by several different modules. The most
important of these is mod_authz_host. Other modules
discussed in this document include mod_setenvif and
mod_rewrite.
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 Allow and
Deny directives let
you allow and deny access based on the host name, or host
address, of the machine requesting a document. The
Order directive goes
hand-in-hand with these two, and tells Apache in which order to
apply the filters.
The usage of these directives is:
Allow from address
where address is an IP address (or a partial IP address) or a fully qualified domain name (or a partial domain name); you may provide multiple addresses or domain names, if desired.
For example, if you have someone spamming your message board, and you want to keep them out, you could do the following:
Deny from 10.252.46.165
Visitors coming from that address 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.
Deny from 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:
Deny from 192.168.205
Deny from phishers.example.com moreidiots.example
Deny from ke
Using Order will let you
be sure that you are actually restricting things to the group that you want
to let in, by combining a Deny and an Allow directive:
Order deny,allow
Deny from all
Allow from dev.example.com
Listing just the Allow
directive would not do what you want, because it will let folks from that
host in, in addition to letting everyone in. What you want is to let
only those folks in.
mod_authz_host, in conjunction with
mod_setenvif, can be used to restrict access to
your website based on the value of arbitrary environment variables.
This is done with the Allow from env= and Deny
from env= syntax.
SetEnvIf User-Agent BadBot GoAway=1
Order allow,deny
Allow from all
Deny from env=GoAway
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.
In the above example, the environment variable GoAway
is set to 1 if the User-Agent matches the
string BadBot. Then we deny access for any request when
this variable is set. This blocks that particular user agent from
the site.
An environment variable test can be negated using the =!
syntax:
Allow from env=!GoAway
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.
You should also read the documentation for
mod_auth_basic and mod_authz_host which
contain some more information about how this all works.
mod_authn_alias can also help in simplifying certain
authentication configurations.
See the Authentication and Authorization howto.
Apache HTTP Server Version 2.2
인증(authentication)은 자신이 누구라고 주장하는 사람을 확인하는 절차이다. 권한부여(authorization)는 가고 싶은 곳으로 가도록 혹은 원하는 정보를 얻도록 허용하는 과정이다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
당신의 웹사이트에 있는 정보가 소수의 사람들만의 비밀이거나 이들만을 위한 정보라면, 이 글에서 설명하는 기법을 사용하여 당신이 보길 원하는 사람만 페이지를 보도록 할 수 있다.
이 글은 웹사이트의 일부를 보호하기위해 많은 사람들이 사용하는 "표준적인" 방법을 다룬다.
이 글에서 다루는 지시어는 서버의 주설정파일(일반적으로
<Directory>
섹션)이나 디렉토리별 설정파일(.htaccess 파일)에서
사용한다.
.htaccess 파일을 사용하려면 이 파일에 있는
인증 지시어를 허용하도록 서버를 설정해야 한다. 이를 위해
디렉토리별 설정파일에 어떤 지시어를 사용할 수 있는지를 결정하는
AllowOverride 지시어를
사용한다.
여기서는 인증을 다루기 때문에, 다음과 같은
AllowOverride 지시어가 필요하다.
AllowOverride AuthConfig
혹은 지시어를 직접 서버 주설정파일에 적는다면, 그 파일에 쓰기 권한이 물론 있어야 한다.
그리고 보호할 파일이 어디있는지 알기위해 서버의 디렉토리 구조에 대해 조금 알아야한다. 이 일은 어렵지않고, 적당한 때에 자세히 설명할 것이다.
이제 서버의 디렉토리를 암호로 보호하는 기본적인 방법을 설명한다.
먼저 암호파일을 만들어야 한다. 이 파일은 웹에서 접근할
수 없는 곳에 있어야 한다. 다른사람이 암호파일을 다운로드하지
못하게하기 위해서다. 예를 들어, 문서들이
/usr/local/apache/htdocs에 있다면 암호파일(들)은
/usr/local/apache/passwd에 둔다.
아파치에 포함된 htpasswd 도구를 사용하여
암호파일을 만든다. 이 프로그램은 아파치를 설치한 곳의
bin 디렉토리에 있다. 파일을 만들려면 다음과
같이 입력한다.
htpasswd -c /usr/local/apache/passwd/passwords rbowen
htpasswd는 암호를 물어보고, 확인을 위해
암호를 다시 입력하라고 요청한다.
# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen
물론 htpasswd이 실행파일 경로에 없다면
실행파일의 전체 경로를 입력해야 한다. 내가 사용하는 서버에서는
/usr/local/apache/bin/htpasswd에 실행파일이
있다.
다음으로 서버가 암호를 요청하도록 설정하고, 서버에게
어떤 사용자의 접근을 허용할지 알려줘야 한다.
httpd.conf를 편집하거나 .htaccess
파일을 사용하여 설정한다. 예를 들어,
/usr/local/apache/htdocs/secret 디렉토리를
보호하려면, 아래 지시어를
/usr/local/apache/htdocs/secret/.htaccess 파일이나
httpd.conf의 <Directory
/usr/local/apache/apache/htdocs/secret> 섹션에 적어야
한다.
AuthType Basic
AuthName "Restricted Files"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen
지시어를 하나씩 살펴보자. AuthType 지시어는 사용자를 인증할
방법을 선택한다. 가장 일반적인 방법은 Basic으로,
mod_auth_basic이 구현한다. 그러나 Basic
인증은 브라우저가 서버로 암호를 암호화하지 않고 보낸다.
그러므로 기밀 자료를 보호하기위해 이 방법을 사용하면 안된다.
아파치는 AuthType Digest라는 인증 방법도 지원한다.
이 방법은 mod_auth_digest가 구현하며, 매우
안전하다. 가장 최근 클라이언트들만이 Digest 인증을 지원한다고
한다.
AuthName 지시어는
인증에 사용할 영역(realm)을 지정한다. 영역은
두가지 역할을 한다. 첫번째는 클라이언트가 보통 이 정보를
암호 대화창에 보여준다. 두번째는 영역 정보를 사용하여
클라이언트가 특정 인증구역에 어떤 암호를 보낼지 결정한다.
예를 들어, 일단 클라이언트가 "Restricted Files"
영역에 인증이 성공하였다면, 클라이언트는 자동으로 같은 서버에서
"Restricted Files" 영역으로 표시된 구역에 대해
동일한 암호를 시도한다. 그래서 여러 제한 구역이 같은 영역을
공유하면 사용자가 여러번 암호를 입력하지 않아도 된다. 물론
보안상 이유로 클라이언트는 서버의 호스트명이 다르면 항상
새로 암호를 물어본다.
AuthUserFile
지시어는 우리가 방금 htpasswd로 만든 암호파일의
경로를 설정한다. 사용자가 많다면 요청마다 매번 사용자를
인증하기위해 일반 문서파일을 검색하는데 시간이 상당히 많이
걸릴 수 있다. 아파치는 빠른 데이타베이스 파일에 사용자 정보를
저장할 수 있다. mod_authn_dbm 모듈은 AuthDBMUserFile 지시어를
제공한다. dbmmanage
프로그램을 사용하여 암호파일을 만들고 다룬다. 아파치 모듈
데이타베이스에는 여러 다른 인증 방식을 제공하는 제삼자가
만든 모듈들이 있다.
마지막으로 Require
지시어는 서버의 특정 영역에 접근할 수 있는 사용자를 지정하여
권한부여를 한다. 다음 절은 require 지시어를
사용하는 다양한 방법을 설명한다.
위의 지시어는 디렉토리로 (사용자명이 rbowen인)
한 사람만을 들여보낸다. 대부분의 경우 여러 사람을 들여보내고
싶을 것이다. 이제 AuthGroupFile을
사용할 때다.
여러 사람을 들여보내고 싶다면 그룹명과 그 그룹에 어떤 사용자들이 있는지 알려주는 그룹파일이 필요하다. 이 파일의 형식은 매우 간단하여, 아무 편집기로나 만들 수 있다. 파일내용은 다음과 같다.
GroupName: rbowen dpitts sungo rshersey
그냥 공백으로 구분한 긴 그룹 구성원 목록일 뿐이다.
기존의 암호파일에 사용자를 추가하려면 다음과 같이 입력한다
htpasswd /usr/local/apache/passwd/passwords dpitts
전과 같지만, 새로 파일을 만들지 않고 기존 파일에 사용자를
추가한다. (-c 옵션은 새로 암호파일을 만든다).
이제 .htaccess 파일을 다음과 같이 수정한다.
AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group GroupName
그러면 GroupName 그룹에 속하며
password 파일에 항목이 있는 사용자가 올바른
암호를 입력하면 접근을 허용한다.
여러 일반 사용자를 들여보내는 다른 방법이 있다. 그룹파일을 만들 필요없이 다음 지시어를 사용하기만 하면 된다.
Require valid-user
Require user rbowen 대신 이 지시어를 사용하면
암호파일에 있는 누구라도 올바른 암호를 입력하기만 하면 접근을
허용한다. 그룹별로 다른 암호파일을 사용하여 그룹과 비슷한
효과를 얻을 수도 있다. 이 경우 아파치가 파일 두개(암호파일과
그룹파일)가 아닌 파일 한개(암호파일)만 검사하면 된다는 것이
장점이다. 그러나 여러 암호파일을 관리해야 하고, AuthUserFile 지시어에
정확한 암호파일을 지정해야 하는 것은 단점이다.
Basic 인증 방식은 서버에서 문서를 요청할 때마다 사용자명과 암호를 확인한다. 심지어 같은 페이지를 새로 고침할 때도 페이지와 (그림이 암호로 보호하는 디렉토리에 있는 경우) 페이지에 있는 모든 그림에 대해 다시 확인한다. 짐작하듯이 속도가 조금 느려진다. 암호파일을 열어서 사용자명을 찾을 때까지 사용자 목록을 살펴봐야 하기때문에 암호파일 크기가 커질 수록 더 느려진다. 그리고 이 작업을 페이지를 요청할 때마다 진행한다.
그래서 현실적으로 한 암호파일에 저장할 수 있는 사용자수에는 한계가 있다. 이 한계는 사용하는 서버의 성능에 따라 다르지만, 항목이 수백개가 넘는다면 느려진다고 생각하고 다른 인증 방법을 고려해야 한다.
사용자명과 암호를 사용한 인증이 다가 아니다. 종종 접속한 장소와 같은 다른 정보를 가지고 사용자를 들여보내고 싶을 때가 있다.
Allow와
Deny 지시어는
문서를 요청한 컴퓨터의 호스트명 혹은 호스트 주소를 가지고
접근을 허용하거나 거부한다. Order 지시어는 이 두
지시어와 같이 사용하여, 아파치에게 어떤 순서로 규칙을 적용할지
알린다.
이들 지시어 사용법은 다음과 같다.
Allow from address
여기서 address는 IP 주소(혹은 IP 주소 일부)나 완전한 도메인명(혹은 도메인명 일부)이다. 원한다면 여러 주소나 도메인명을 사용할 수 있다.
예를 들어, 누군가가 게시판에 광고를 올리고 있다면 다음과 같이 접근을 막을 수 있다.
Deny from 205.252.46.165
그 주소에서 들어오는 방문자는 이 지시어가 보호하는 페이지를 볼 수 없다. IP 주소 대신 다음과 같이 컴퓨터명을 사용할 수도 있다.
Deny from host.example.com
또, 전체 도메인의 접근을 막으려면 주소나 도메인명의 일부를 사용한다.
Deny from 192.101.205
Deny from cyberthugs.com moreidiots.com
Deny from ke
Order를
Deny와 Allow 지시어와 같이
사용하여 실제로 원하는 대상을 막을 수 있다.
Order deny,allow
Deny from all
Allow from dev.example.com
Allow
지시어만 사용하면, 해당 호스트의 사용자를 허용하고 거기에
추가로 모든 사람을 허용하므로 원하는 결과를 얻지 못한다.
당신은 특정 사람만 허용하길 원한다.
mod_auth_basic과
mod_authz_host 문서에 접근제어가 동작하는
방법에 대한 더 많은 정보가 있다.
Apache HTTP Server Version 2.2
| 관련된 모듈 | 관련된 지시어 |
|---|---|
CGI (Common Gateway Interface)는 웹서버가 보통 CGI 프로그램 혹은 CGI 스크립트라고 부르는, (웹페이지 내용을 만드는) 외부 프로그램과 통신하는 방법을 정의한다. 웹사이트에서 동적인 페이지를 만드는 가장 흔하고 간단한 방법이다. 이 문서는 아파치 웹서버에 CGI를 구성하는 방법을 소개하고, CGI 프로그램을 작성해본다.
CGI 프로그램이 올바로 동작하려면 CGI 실행이 가능하도록 아파치를 설정해야 한다. 설정하는 방법은 여러가지다.
ScriptAlias
지시어를 사용하면 아파치는 특정 디렉토리를 CGI 프로그램용으로
둔다. 아파치는 이 디렉토리에 있는 모든 파일이 CGI
프로그램이라고 가정하여 클라이언트가 자원을 요청하면 자원을
실행하려고 시도한다.
ScriptAlias
지시어는 다음과 같이 사용한다.
ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
위 예제는 아파치를 기본 장소에 설치한 경우
httpd.conf 설정파일에 있는 내용이다. ScriptAlias 지시어는 Alias 지시어와 같이 URL
앞부분을 특정 디렉토리로 대응한다.
Alias와
ScriptAlias는 보통 DocumentRoot 디렉토리 밖에 있는
디렉토리에 사용한다. Alias와
ScriptAlias의 차이점은
ScriptAlias가 추가로 URL 앞부분으로
시작하는 모든 파일을 CGI 프로그램으로 취급하는 점이다.
그래서 위의 설정은 아파치에게 /cgi-bin/으로
시작하는 자원을 요청하면
/usr/local/apache2/cgi-bin/ 디렉토리에서
찾아서 CGI 프로그램으로 처리하라고 알린다.
예를 들어, URL
http://www.example.com/cgi-bin/test.pl을
요청하면 아파치는
/usr/local/apache2/cgi-bin/test.pl 파일을
실행하여 결과를 반환한다. 물론 파일이 존재하고 실행가능하며
어떤 방법으로든 출력을 해야 한다. 그렇지 않으면 아파치는
오류문을 보낸다.
보통 보안상 이유때문에 CGI 프로그램은 ScriptAlias한 디렉토리에
한정한다. 그래서 관리자는 누가 CGI 프로그램을 사용할 수
있는지 엄격히 감독할 수 있다. 그러나 적당한 보안조치를
취했다면 아무 디렉토리에서나 CGI 프로그램을 실행하지 않을
이유가 없다. 예를 들어, UserDir 지시어를 사용하여
사용자가 자신의 홈디렉토리에 웹페이지를 가지는 경우를
가정하자. 사용자가 자신의 CGI 프로그램을 사용하고 싶은데
cgi-bin 디렉토리에 접근권한이 없다면, 다른
곳에서라도 CGI 프로그램을 실행하고 싶을 것이다.
아무 디렉토리에서나 CGI 실행을 허용하려면 두 과정이
필요하다. 먼저, AddHandler나 SetHandler 지시어를 사용하여
cgi-script 핸들러를 작동해야 한다. 두번째로,
Options 지시어에
ExecCGI를 지정해야 한다.
서버의 주설정파일에 직접 Options 지시어를 사용하여 특정
디렉토리에서 CGI 실행을 허용할 수 있다.
<Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
</Directory>
위 지시어로 아파치는 CGI 파일의 실행을 허용한다. 어떤
파일이 CGI 파일인지도 서버에게 알려야 한다. 다음 AddHandler 지시어는 서버에게
확장자가 cgi나 pl인 파일은 모두
CGI 프로그램이라고 알린다.
AddHandler cgi-script .cgi .pl
.htaccess 투토리얼은
httpd.conf에 접근권한이 없는 경우에 CGI 프로그램을
사용할 수 있는 방법을 알려준다.
아래 설정을 사용하면 사용자 디렉토리에서 .cgi로
끝나는 파일을 CGI 프로그램으로 실행한다.
<Directory /home/*/public_html>
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>
다음을 사용하면 사용자 디렉토리의 cgi-bin
하위디렉토리에 있는 모든 파일을 CGI 프로그램으로 인식한다.
<Directory /home/*/public_html/cgi-bin>
Options ExecCGI
SetHandler cgi-script
</Directory>
``일반적인'' 프로그래밍과 CGI 프로그래밍 사이에는 두가지 주된 차이점이 있다.
첫번째 차이는 CGI 프로그램은 다른 출력을 하기전에 먼저 MIME-type 헤더를 출력해야 한다는 점이다. HTTP 헤더는 클라이언트에게 클라이언트가 어떤 내용을 받게될지 미리 알린다. 보통 다음과 같다.
Content-type: text/html
두번째 차이는 HTML 혹은 브라우저가 보여줄 수 있는 형식으로 출력해야 한다는 점이다. 대부분의 경우 HTML을 출력하지만, 때때로 gif 그림과 같이 HTML이 아닌 내용을 출력하는 CGI 프로그램을 작성하는 경우도 있다.
두가지를 제외하고는 CGI 프로그램 작성은 이미 만들어 보았을 다른 프로그램들과 매우 비슷하다.
다음은 브라우저에 한 줄을 찍는 CGI 프로그램 예제다.
그대로 first.pl이라는 파일에 저장하고,
cgi-bin 디렉토리에 복사한다.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";
Perl에 익숙하지 않더라도 무슨 일이 일어나는지 알 수
있다. 첫번째 줄은 아파치(혹은 사용하는 쉘)에게
/usr/bin/perl 위치에 있는 인터프리터을 사용하여
이 프로그램 파일을 실행하라고 알린다. 두번째 줄은 방금
말한 content-type 선언을 출력하고 carriage-return 줄바꿈을
두번 출력한다. 그러면 헤더 뒤에 HTTP 헤더의 끝을 뜻하는
빈줄이 생기고, 본문이 시작한다. 세번째 줄은 "Hello, World."
문자열을 출력한다. 이것으로 끝이다.
브라우저를 실행하고 주소를 입력한다
http://www.example.com/cgi-bin/first.pl
파일 장소를 입력하면, 브라우저창에 Hello, World.
한 줄이 보인다. 흥분되지는 않지만, 한번 동작하는 것을
보았으니 이제 다른 것을 시도해 볼 수 있다.
웹에서 CGI 프로그램에 접근할때 브라우저에 나올 수 있는 내용은 기본적으로 네가지다.
Content-Type을 설정하였는지 확인한다.서버는 당신과 동일한 계정으로 동작하지 않음을 명심하라.
즉, 서버가 시작하면 서버는 비특권 사용자 권한(보통
nobody나 www)으로 동작한다.
그래서 당신이 소유한 파일을 실행하려면 권한이 필요하다.
파일에 nobody가 실행하기에 충분한 권한을
주기위해 보통 모두에게 파일의 실행 권한을 준다.
chmod a+x first.pl
또, 프로그램이 다른 파일을 읽거나 쓴다면 이 파일에도 적절한 권한이 필요하다.
명령행에서 프로그램을 실행하면 자동으로 어떤 정보가
쉘로 전달된다. 예를 들어, PATH는 쉘에게 당신이
말한 파일을 찾을 장소를 알려준다.
웹서버가 프로그램을 CGI 프로그램으로 실행할때는
PATH가 다를 수 있다. (예를 들어,
sendmail 같이) CGI 프로그램 안에서 실행하는
명령어는 완전한 경로로 명시해야 쉘이 명령어를 찾을 수
있다.
경로 문제는 다음과 같이 CGI 프로그램 첫번째 줄에 나오는
스크립트 인터프리터 (보통 perl) 경로에서
자주 발생한다.
#!/usr/bin/perl
실제로 인터프리터의 경로인지 확인한다.
또, CGI 프로그램이 다른 환경변수를 사용한다면 아파치가 이 변수들을 프로그램에게 전달해야 한다.
CGI 프로그램이 실패하는 경우 대부분 프로그램 자체 문제때문이다. 특히 위의 두가지 실수를 하지 않았고 이 글을 계속 보고 있다면 더더욱 그렇다. 먼저 웹서버에서 실행하기 전에 명령행에서 프로그램을 실행해본다. 예를 들어, 다음과 같이 실행한다.
cd /usr/local/apache2/cgi-bin
./first.pl
(perl 인터프리터를 실행하지 마라. 쉘과
아파치는 스크립트 첫번째 줄에 있는 경로 정보를 사용하여 인터프리터를
찾아야 한다.)
프로그램은 제일 먼저 Content-Type을 포함한
HTTP 헤더들을 출력하고 빈 줄을 출력해야 한다. 다른 것을
출력한다면 웹서버에서 실행할 경우 아파치는 Premature
end of script headers를 반환한다. 자세한 내용은
위의 CGI 프로그램 작성하기를 참고하라.
오류 로그는 당신 편이다. 무언가 잘못되면 오류 로그에 문구가 생긴다. 오류 로그를 제일 먼저 살펴봐야 한다. 웹사이트를 호스팅하는 곳에서 오류 로그를 보지 못하게 한다면, 아마도 다른 업체를 알아봐야 한다. 오류 로그를 보는 방법을 익히면, 대부분의 문제를 빨리 파악하여 해결할 수 있다.
suexec 지원 프로그램을
사용하면 어떤 가상호스트 혹은 어떤 사용자 디렉토리에 있는지에
따라 CGI 프로그램을 다른 사용자 권한으로 실행할 수 있다.
Suexec는 매우 엄격하게 권한을 검사하며, 검사를 하나라도
통과하지 못하면 CGI 프로그램을 실행하지 않고 Premature
end of script headers를 반환한다.
suexec를 사용하고 있는지 알려면 apachectl -V를
실행하여 SUEXEC_BIN 위치를 확인한다. 아파치가
시작할때 그 장소에서 suexec 실행파일을 발견하면, suexec를
사용할 수 있다.
suexec를 완전히 이해하지 못했다면 사용해서는 안된다.
suexec를 사용하지 않으려면 SUEXEC_BIN 위치에
있는 suexec 실행파일을 지우고 (혹은 파일명을
바꾸고) 서버를 재시작하면 된다. suexec에 대해 읽은 다음 그래도
사용하고 싶다면, suexec -V를 실행하여 suexec
로그파일 위치를 알아내고 로그파일에서 당신이 어떤 규칙을
어기고 있는지 찾는다.
CGI 프로그래밍에 익숙해질수록 뒤에서 벌어지는 일을 이해하면 도움이 된다. 구체적으로 브라우저와 서버가 서로 통신하는 방법을 말하는 것이다. 몰라도 "Hello, World."를 출력하는 프로그램을 작성할 수 있지만 이런 프로그램은 별로 쓸모가 없기때문이다.
환경변수는 당신이 컴퓨터를 사용하는 동안 당신 주위를
떠다니는 값이다. 환경변수는 path (컴퓨터가 당신이 입력한
명령어에 해당하는 실제 파일을 찾는 장소), 사용자명, 터미널
종류와 같이 유용한 정보다. 일반적인 환경변수를 모두 보려면
명령행 프롬프트에서 env를 입력한다.
CGI를 실행할때도 서버와 브라우저는 각자의 환경변수를 서로 교환한다. 이 정보에는 브라우저 종류 (Netscape, IE, Lynx), 서버 종류 (아파치, IIS, WebSite), 실행하는 CGI 프로그램명 등이 있다.
CGI 프로그래머는 이런 변수들을 사용할 수 있고, 환경변수는 클라이언트-서버 통신에는 일부분을 차지한다. 전체 필수 변수 목록은 http://hoohoo.ncsa.uiuc.edu/cgi/env.html에 있다.
아래 간단한 Perl CGI 프로그램은 자신에게 전달된 모든
환경변수를 보여준다. 아파치 배포본의 cgi-bin
디렉토리에 이와 비슷한 프로그램이 두개 있다. 몇몇 변수는
필수이고 나머지는 선택적이다. 그래서 공식 목록에 없는
변수도 보인다. 또, 아파치는 기본적으로 제공하는 환경변수
외에 여러가지 방법으로 직접 환경변수를
추가할 수 있다.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
}
또, 서버와 클라이언트는 표준입력(STDIN)과
표준출력(STDOUT)으로 통신한다. 일상적인 경우
STDIN은 키보드나 프로그램이 처리하는 파일을
나타내고, STDOUT은 보통 콘솔이나 화면을 뜻한다.
CGI 프로그램에게 웹 양식(form)을 POST하면
양식에 입력한 자료를 특별한 형식으로 묶어서 CGI 프로그램의
STDIN으로 전달한다. 그러면 프로그램은 키보드나
파일에서 얻은 자료를 처리하듯이 자료를 처리할 수 있다.
"특별한 형식"은 매우 간단하다. 항목 이름과 값을 등호(=)로 연결하고, 항목 이름과 값의 쌍들을 서로 앤퍼샌드(&)로 연결한다. 공백, 앰퍼샌드, 등호 같은 부자연스러운 문자는 혼동하지 않도록 16진수로 변환한다. 완전한 자료 문자열은 다음과 같이 생겼다.
name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
종종 URL 뒤에서 이런 문자열을 보게 된다. 이 경우 서버는
문자열을 QUERY_STRING이라는 환경변수에 저장한다.
이를 GET 요청이라고 한다. FORM
태그의 METHOD 속성을 지정하여 HTML 양식(form)이
자료를 GET할지 POST할지 결정한다.
이제 프로그램은 이런 문자열을 유용한 정보로 쪼개야 한다. 다행히도 이런 자료 처리를 돕고 CGI 프로그램의 다른 여러 면을 살피는 라이브러리와 모듈들이 있다.
CGI 프로그램을 작성할때 지루한 작업을 대신해주는 코드 라이브러리 혹은 모듈을 사용할지 고려해봐야 한다. 이런 것을 사용하면 버그가 줄고 더 빨리 프로그램을 개발할 수 있다.
Perl로 CGI 프로그램을 작성한다면 CPAN에서 관련 모듈들을 찾을
수 있다. CGI 개발에 가장 널리 사용되는 모듈은
CGI.pm이다. 대부분의 프로그램에 충분한 최소
기능을 구현한 CGI::Lite도 고려해 볼 수 있다.
C로 CGI 프로그램을 작성한다면 선택의 여지가 많다. 이중
하나가 http://www.boutell.com/cgic/에
있는 CGIC 라이브러리다.
웹에 매우 많은 CGI 정보가 있다. 뉴스그룹 comp.infosystems.www.authoring.cgi에서 여러 사람들과 CGI 문제를 논의할 수 있다. HTML Writers Guild의 -servers 메일링리스트는 질문에 대한 답을 찾기에 훌륭한 장소다. http://www.hwg.org/lists/hwg-servers/에서 더 많은 것을 알 수 있다.
그리고 물론 CGI 프로그램 동작에 대한 모든 내용을 설명한 CGI 규약을 읽어야 할지도 모른다. NCSA에 원본 문서가 있고, 수정한 초안은 Common Gateway Interface RFC 프로젝트에 있다.
메일링리스트나 뉴스그룹에 현재 격고 있는 CGI 문제에 대해 질문할때는 발생한 현상과 원래 기대한 결과, 실제로 발생한 현상이 어떻게 다른지, 사용하는 서버, CGI 프로그램을 작성한 언어, 가능하면 해당 코드를 자세히 적어라. 그러면 해결책을 찾기 쉬워진다.
아파치 소스코드가 잘못되었다고 확신하지 않는 한 CGI 질문을 아파치 버그 데이터베이스에 올리면 절대로 안된다.
Apache HTTP Server Version 2.2
.htaccess 파일을 사용하여 디렉토리별로 설정을
변경할 수 있다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
.htaccess 파일(혹은 "분산 설정파일")을
사용하면 디렉토리별로 설정을 변경할 수 있다. 여러 설정 지시어가
있는 파일을 특정 문서 디렉토리에 두면, 그 디렉토리와 모든
하위디렉토리에 지시어를 적용한다.
.htaccess 파일명을 다르게 사용하고 싶다면,
AccessFileName 지시어를
사용하여 변경할 수 있다. 예를 들어, .config
파일명을 사용하려면 서버 설정파일에 다음과 같이 추가한다.
AccessFileName .config
일반적으로 .htaccess 파일은 주설정파일과 문법이
같다. AllowOverride
지시어가 이 파일에 나올 수 있는 내용을 결정한다. 이 지시어는
.htaccess 파일에서 허용하는 지시어 분류를 지정한다.
지시어를 .htaccess 파일에서 사용할 수 있다면,
해당 지시어 문서의 Override 항목은 지시어를 허용하기위해
AllowOverride에 사용할
값을 알려준다.
예를 들어, AddDefaultCharset
지시어 문서를 보면 이 지시어를 .htaccess 파일에서
사용할 수 있다. (지시어 요약에서 사용장소 항목을 보라.)
Override
줄에 FileInfo가 있다. 그래서 이 지시어를
.htaccess 파일에서 사용하기위해서는 최소한
AllowOverride FileInfo가 필요하다.
특정 지시어를 .htaccess 파일에서 사용할
수 있는지 궁금하면 지시어 문서의 사용장소 항목에 ".htaccess"가
있는지 확인한다.
일반적으로 주서버파일에 접근할 수 없는 경우가 아니라면
.htaccess 파일을 사용하면 안된다. 예를 들어,
사용자 인증이 항상 .htaccess 파일에 있어야
한다는 것은 잘못 알려진 오해다. 이는 사실이 아니다. 주서버설정에
사용자 인증 설정을 적을 수 있고, 사실 이러길 권한다.
.htaccess 파일은 컨텐츠 제공자가 디렉토리별로
서버 설정을 다르게하고 싶지만 서버 시스템에 root 권한이
없는 경우에 사용한다. 서버 관리자가 설정을 자주 변경하고
싶지 않은 경우 일반 사용자가 직접 .htaccess
파일을 수정하도록 허용하는 것이 바람직하다. 예를 들어, 한
컴퓨터에 여러 사용자 사이트를 서비스하는 ISP에서 사용자가
자신의 설정을 변경하고 싶은 경우가 그러하다.
그러나 일반적으로 .htaccess 파일은 가급적
피해야 한다. .htaccess 파일에서 허용하는 지시어는
주설정파일의 <Directory> 섹션과 같은 효과가
있다.
다음 두가지 큰 이유때문에 .htaccess 파일
사용을 피해야 한다.
첫번째는 성능이다. AllowOverride가 .htaccess
파일을 사용하도록 허용하면, 아파치는 디렉토리마다
.htaccess 파일을 찾는다. 그래서
.htaccess 파일을 허용하면 실제로 파일을 사용하지
않는 경우에도 성능이 떨어진다! 또, .htaccess
파일은 문서를 요청할때마다 읽어들인다.
게다가 적용해야 하는 전체 지시어를 모으기위해 아파치는
모든 상위 디렉토리에서 .htaccess 파일을 찾는다.
(어떻게 지시어를 적용하나 절을 참고.)
그래서 /www/htdocs/example 디렉토리에 있는
파일을 요청하면, 아파치는 다음 파일들을 찾아야 한다.
/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess
그래서 그 디렉토리에 있는 파일을 접근할 때마다 설정파일이
전혀 없어도 파일시스템을 4번 더 접근해야 한다.
(/에서도 .htaccess 파일을 허용한
경우를 말한다. 보통은 허용하지 않는다.)
두번째 이유는 보안이다. 사용자에게 서버설정 변경 권한을
주면 당신이 감당할 수 없는 변화가 일어날 수 있다. 사용자에게
이런 권한을 줄지 곰곰이 생각하라. 또, 사용자가 원하는 것보다
적은 권한을 주면 기술지원요청이 들어온다. 사용자에게 가능한
권한 수준을 명확히 알려라. 사용자에게 AllowOverride를 어떻게 설정하였는지
정확히 알리고 관련 문서를 제공하면 앞으로 혼란을 피할 수
있다.
지시어를 /www/htdocs/example 디렉토리의
.htaccess 파일을 두는 것과 주서버설정의
<Directory /www/htdocs/example> Directory
설정에 두는 것은 완전히 같다.
/www/htdocs/example에 있는
.htaccess 섹션:
/www/htdocs/example에 있는
.htaccess 파일 내용
AddType text/example .exm
httpd.conf 파일에 있는 섹션
<Directory /www/htdocs/example>
AddType text/example .exm
</Directory>
그러나 파일을 요청할 때마다 설정을 읽지않고 아파치가 시작할때 한번만 설정을 읽기때문에 같은 설정을 서버설정파일에 사용하면 성능이 더 빠르다.
AllowOverride 지시어를
none으로 설정하면 .htaccess 파일을
완전히 사용할 수 없다.
AllowOverride None
.htaccess 파일을 발견한 디렉토리와 그 디렉토리의
모든 하위디렉토리에 .htaccess 파일에 있는 설정
지시어를 적용한다. 그래서 상위디렉토리의 .htaccess
파일을 주의해야 한다. 발견한 순서로 지시어를 적용한다. 특정
디렉토리에 있는 .htaccess 파일은 상위디렉토리에
있는 .htaccess 파일의 지시어를 무효로 만들
수 있고, 상위디렉토리에 있는 지시어는 더 상위디렉토리 혹은
주설정파일에 있는 지시어를 무효로 만들 수 있다.
예제:
/www/htdocs/example1 디렉토리에 다음과 같은
.htaccess 파일이 있다.
Options +ExecCGI
(주의: .htaccess 파일에 "Options" 지시어를 사용하려면
"AllowOverride Options"가 필요하다.)
/www/htdocs/example1/example2 디렉토리에는
다음과 같은 .htaccess 파일이 있다.
Options Includes
이 두번째 .htaccess 파일의
Options Includes가 이전 설정을 완전히 무효로
만들기때문에 /www/htdocs/example1/example2
디렉토리는 CGI 실행을 허용하지 않는다.
인증 방법을 알기위해 바로 이곳부터 읽는다면 주의할 것이
있다. 암호 인증을 하려면 .htaccess 파일이
필요하다는 오해가 널리 퍼져있다. 이는 사실이 아니다.
주설정파일의 <Directory> 섹션에 인증 지시어를
두는 것이 더 권장하는 방법이고, 서버의 주설정파일을 수정할
수 없는 경우에만 .htaccess 파일을 사용해야
한다. 언제 .htaccess 파일을 사용해야 하는지와
사용하지 말아야 하는지는 위에서
설명하였다.
앞에서 말했지만 아직도 .htaccess 파일이
필요하다고 생각되면 아래 설정이 도움이 될 것이다.
.htaccess 파일 내용.
AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins
이 지시어가 동작하기위해서는
AllowOverride AuthConfig 지시어가 필요함을
명심하라.
인증과 권한부여에 대한 자세한 설명은 인증 투토리얼을 보길 바란다.
또다른 일반적인 .htaccess 파일의 용도는
특정 디렉토리에서 Server Side Includes를 가능하게 만드는
것이다. 원하는 디렉토리의 .htaccess 파일에
다음과 같은 설정 지시어를 사용하면 된다.
Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml
이 지시어가 동작하려면 AllowOverride Options와
AllowOverride FileInfo가 모두 필요함을 명심하라.
server-side includes에 대한 자세한 설명은 SSI 투토리얼을 보길 바란다.
마지막으로 .htaccess 파일을 사용하여 특정
디렉토리에서 CGI 프로그램 실행을 허용하고 싶다면, 다음과
같은 설정을 사용한다.
Options +ExecCGI
AddHandler cgi-script cgi pl
혹은 이 디렉토리에 있는 모든 파일을 CGI 프로그램으로 처리하고 싶다면 다음과 같은 설정도 가능하다.
Options +ExecCGI
SetHandler cgi-script
이 지시어가 동작하려면 AllowOverride Options와
AllowOverride FileInfo가 모두 필요함을 명심하라.
CGI 프로그래밍과 설정에 대한 자세한 설명은 CGI 투토리얼을 보길 바란다.
.htaccess 파일에 둔 설정 지시어가 원하는
기능을 하지 않는 경우 여러가지 이유가 있을 수 있다.
가장 일반적인 문제는 설정 지시어를 가능하게 만드는 AllowOverride를 설정하지 않은
경우다. 문제가 되는 파일 영역에 AllowOverride None이
없는지 확인한다. .htaccess 파일을 아무렇게나
적은 다음 페이지를 다시 접근하여 쉽게 검사해볼 수 있다.
서버 오류가 나오지 않으면 거의 확실히
AllowOverride None을 사용한 경우다.
반대로 문서에 접근할때 서버 오류가 발생하면 아파치 오류로그를
살펴봐라. 아마도 .htaccess 파일에 있는 지시어를
허용하지 않는다고 할 것이다. 아니고 문법 오류가 있다면 오류를
고친다.
Apache HTTP Server Version 2.2
인증(authentication)은 자신이 누구라고 주장하는 사람을 확인하는 절차이다. 권한부여(authorization)는 가고 싶은 곳으로 가도록 혹은 원하는 정보를 얻도록 허용하는 과정이다.
참고: 인증, 권한부여, 접근제어
CGI (Common Gateway Interface)는 웹서버가 보통 CGI 프로그램 혹은 CGI 스크립트하고 부르는, (웹페이지 내용을 만드는) 외부 프로그램과 상호작용하는 방법을 정의한다. 웹사이트에서 동적인 페이지를 만드는 가장 흔하고 간단한 방법이다. 이 문서는 아파치 웹서버에 CGI를 구성하는 방법을 소개하고, CGI 프로그램을 작성해본다.
참고: CGI: 동적 페이지 생성
.htaccess 파일.htaccess 파일을 사용하여 디렉토리별로
설정을 변경할 수 있다. 여러 설정 지시어가 있는 파일을
특정 문서 디렉토리에 두면, 그 디렉토리와 모든 하위디렉토리에
지시어를 적용한다.
참고: .htaccess
파일
SSI (Server Side Includes)는 HTML 페이지에 사용하는 지시어로, 페이지를 서비스할때 서버가 처리한다. SSI를 사용하면 CGI 프로그램이나 다른 동적인 기술로 페이지 전체를 만들어서 서비스하지 않고도 HTML 페이지에 동적으로 생성한 내용을 추가할 수 있다.
Apache HTTP Server Version 2.2
여러 사용자가 있는 시스템에서 UserDir 지시어를 사용하면
각 사용자는 자신의 홈디렉토리 안에 웹사이트를 만들 수 있다.
URL http://example.com/~username/에 접근하면
사용자 "username"의 홈디렉토리에서 UserDir 지시어로 지정한
하위디렉토리에 있는 페이지를 가져오게 된다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
UserDir
지시어는 사용자별 페이지를 가져올 디렉토리를 지정한다. 이
지시어의 사용법은 여러가지다.
슬래쉬로 시작하지않는 경로를 지정하면 각 사용자의 홈디렉토리에 상대적인 디렉토리 경로로 처리한다. 예를 들어, 아래 설정의 경우:
UserDir public_html
URL http://example.com/~rbowen/file.html은
파일 경로 /home/rbowen/public_html/file.html을
뜻한다.
슬래쉬로 시작하는 경로를 지정하면 지정한 디렉토리에 사용자명을 더한 디렉토리 경로를 사용한다. 예를 들어, 아래 설정의 경우:
UserDir /var/html
URL http://example.com/~rbowen/file.html은
파일 경로 /var/html/rbowen/file.html을 뜻한다.
별표 (*)를 포함한 경로를 지정하면 별표를 사용자명으로 대체한 경로를 사용한다. 예를 들어, 아래 설정의 경우:
UserDir /var/www/*/docs
URL http://example.com/~rbowen/file.html은
파일 경로 /var/www/rbowen/docs/file.html을
뜻한다.
UserDir 문서에 있는 문법을 사용하여 사용자별 웹디렉토리 기능을 이용할 수 있는 사용자를 제한할 수 있다:
UserDir enabled
UserDir disabled root jro fish
위 설정은 disabled 문장에 열거한 사람을
제외하고 모든 사용자에게 웹디렉토리 기능을 허락한다. 또,
다음과 같이 몇몇 사용자를 제외하고 기능을 허락하지 않을
수도 있다:
UserDir disabled
UserDir enabled rbowen krietz
UserDir
문서에 있는 다른 예들도 참고하라.
사용자마다 cgi-bin 디렉토리를 부여하려면 <Directory> 지시어를
사용하여 사용자 홈디렉토리의 특정 하위디렉토리를 cgi 가능하게
만든다.
<Directory /home/*/public_html/cgi-bin/>
Options ExecCGI
SetHandler cgi-script
</Directory>
UserDir이 public_html이라고
가정하면, 다음과 같이 그 안에 있는 cgi 프로그램
example.cgi를 실행할 수 있다.
http://example.com/~rbowen/cgi-bin/example.cgi
사용자가 자신의 웹공간에 대한 웹서버 설정을 수정하려면,
.htaccess 파일을 사용할 수 있어야 한다. AllowOverride를 사용자가 수정할
수 있는 지시어에 적합한 값으로 설정하라. 어떻게 동작하는지에
대한 자세한 졍보는 .htaccess
투토리얼을 참고하라.
Apache HTTP Server Version 2.2
Server-side includes를 사용하여 HTML 문서에 동적인 내용을 추가할 수 있다.
| 관련된 모듈 | 관련된 지시어 |
|---|---|
이 글은 보통 SSI라고 부르는 Server Side Includes를 설명한다. SSI가 가능하도록 서버를 설정하는 방법과 HTML 페이지에 동적인 내용을 추가하는 기본적인 SSI 사용법을 소개한다.
이 글의 뒷부분은 SSI 지시어 조건문과 같은 고급기법을 설명한다.
SSI (Server Side Includes)는 HTML 페이지에 사용하는 지시어로, 페이지를 서비스할때 서버가 처리한다. SSI를 사용하면 CGI 프로그램이나 다른 동적인 기술로 페이지 전체를 만들어서 서비스하지 않고도 HTML 페이지에 동적으로 생성한 내용을 추가할 수 있다.
SSI를 사용할지 아니면 프로그램으로 페이지 전체를 생성할지 결정은 페이지에서 정적인 부분이 많은지와 페이지를 서비스할 때마다 어느정도를 다시 계산해야할지에 달렸다. SSI는 현재 시간과 같이 적은 정보를 추가하는데 좋다. 그러나 페이지를 서비스할때 페이지의 대부분을 생성해야 한다면 다른 방법을 찾아봐야 한다.
서버가 SSI를 처리하려면 httpd.conf 파일이나
.htaccess 파일에서 다음 지시어를 사용해야 한다.
Options +Includes
그러면 아파치는 파일에서 SSI 지시어를 처리한다. 설정에는
보통 여러 Options 지시어가
있고, 이 지시어들은 서로 덮어써서 무효로 만들다. 그래서
지시어를 맨마지막에 처리하기위해 보통 SSI를 원하는 특정
디렉토리에서 Options를 사용한다.
모든 파일에서 SSI 지시어를 처리하는 것은 아니다. 아파치에게
어떤 파일을 처리할지 알려줘야 한다. 두가지 방법이 있다.
하나는 다음과 같은 지시어로 .shtml과 같은 특정
파일 확장자를 가진 파일을 처리하는 방법이다.
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
이 방법의 단점은 이미 있는 페이지에 SSI 지시어를 추가하는
경우 SSI 지시어를 처리하기위해 .shtml 확장자를
부여하기때문에 파일명과 이 페이지의 모든 링크를 변경해야
하는 점이다.
다른 방법은 XBitHack
지시어를 사용하는 방법이다.
XBitHack on
XBitHack는
실행권한이 있는 파일에서 SSI 지시어를 처리한다. 그래서 이미
있는 페이지에 SSI 지시어를 추가한다면 파일명을 변경하지
않고 chmod로 파일에 실행권한을 주면 된다.
chmod +x pagename.html
하지 말아야 할 것 하나. 가끔 .shtml 파일명에
골치를 앓지말고 모든 .html 파일을 SSI 처리하라고
충고하는 사람이 있다. 이 사람들은 아마도 XBitHack에 대해 모르는
것 같다. 명심할 점은 이렇게 하면 아파치는 파일에 SSI 지시어가
없더라도 클라이언트로 보내는 모든 파일을 살펴봐야 한다는
것이다. 성능이 매우 느려질 수 있으며, 좋은 생각이 아니다.
물론 윈도우즈에서는 실행권한이란 것이 없기때문에 후자를 사용할 수 없다.
내용이 동적이여서 계산하기 어렵기때문에 아파치 기본 설정은 SSI 페이지의 최근수정일과 content length HTTP 헤더를 보내지 않는다. 그래서 문서를 캐쉬하지 못하고 클라이언트가 느끼는 성능이 떨어진다. 두가지 해결방법이 있다.
XBitHack Full 설정은 사용한다. 그러면
아파치는 포함하는(include) 파일들의 수정일은 무시한체
원래 요청한 파일의 날짜만 보고 최근수정일을 알아낸다.mod_expires에 있는 지시어를 사용하여
파일에 직접 만기일을 설정하면 브라우저와 프록시가 문서를
캐쉬할 수 있다.SSI 지시어의 사용법은 다음과 같다.
<!--#element attribute=value attribute=value ... -->
HTML 주석같이 생겼기때문에 SSI 기능을 가동하지 않아도 HTML 소스에는 나오지만 브라우저는 무시한다. SSI를 올바로 설정하면 지시어를 결과값으로 바꾼다.
element는 다음중 하나다. 다음 회에 더 자세히 설명할 것이다. 지금은 SSI로 할 수 있는 몇가지 예를 보인다
<!--#echo var="DATE_LOCAL" -->
echo element는 변수값을 그대로 출력한다.
CGI 프로그램에 제공하는 환경변수들 외에도 여러 표준 변수가
있다. 또, set element를 사용하여 직접 변수를
정의할 수도 있다.
날짜 출력 형식이 마음에 들지 않는다면, 다음과 같이
config element의 timefmt attribute를
사용한다.
<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->
이 문서는 <!--#flastmod file="index.html" -->에 마지막으로 수정되었다
이 element도 timefmt 형식 설정에 달렸다.
일반적인 SSI 사용법중 하나로, 많이들 애용하는 ``방문수 카운터'' 같은 CGI 프로그램 결과를 출력한다.
<!--#include virtual="/cgi-bin/counter.pl" -->
다음은 HTML 문서에 사용할 수 있는 몇가지 SSI 예제다.
앞에서 SSI를 사용하여 사용자에게 문서의 최근수정일을 알릴 수 있다고 말했다. 그러나 실제 방법은 알려주지 않았다. 다음 코드를 HTML 문서에 사용하면 페이지에 시간 기록을 남긴다. 물론 위에서 설명한대로 SSI가 올바로 작동해야 한다.
<!--#config timefmt="%A %B %d, %Y" -->
이 문서는 <!--#flastmod file="ssi.shtml" -->에 마지막으로 수정되었다;
물론 ssi.shtml대신 원하는 실제 파일명을
사용한다. 아무 페이지에라도 붙여넣을 수 있는 범용코드를
원한다면, 파일명 대신 LAST_MODIFIED 변수를
사용한다.
<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->
timefmt 형식에 대한 자세한 정보는 검색엔진에서
strftime을 찾아봐라. 문법은 같다.
여러 페이지가 있는 사이트를 관리한다면 페이지 전체를 수정하는 것은, 특히 페이지들이 표준 외관을 가지도록 수정하는 것은 정말로 괴롭다.
페이지 상단(header)과 하단(footer)을 파일로 포함하여
이런 수정의 부담을 덜 수 있다. 모든 페이지에서
include SSI 명령어를 사용하여 페이지 하단 파일
하나를 포함하면 된다. include element의
file attribute나 virtual attribute로
포함할 파일을 지정한다. file attribute는 현재
디렉토리에 상대적인 파일경로다. 즉, (/로 시작하는)
절대파일경로나 경로 안에 ../를 사용할 수 없다. 아마도 서비스하는
문서의 상대 URL을 지정할 수 있는 virtual attribute가
더 유용할 것이다. 경로를 /로 시작할 수 있지만, 포함하려는
파일이 서비스하는 파일과 같은 서버에 있어야 한다.
<!--#include virtual="/footer.html" -->
나는 보통 이 두가지를 합쳐서 포함할 페이지 하단 파일에
LAST_MODIFIED 지시어를 넣는다. 포함하려는 파일에도
SSI 지시어가 나올 수 있으며, 이렇게 포함한 파일이 다른 파일을
포함하는 식으로 여러번 계속 포함할 수도 있다.
시간 형식 config(설정) 외에 두가지를 더
config(설정)할 수 있다.
보통 SSI 지시어가 잘못되면 다음과 같은 문구가 나온다
[an error occurred while processing this directive]
이 문구를 변경하고 싶다면 config element의
errmsg attribute를 사용하여 변경한다.
<!--#config errmsg="[It appears that you don't know how to use SSI]" -->
사이트를 서비스하기 전에 모든 SSI 지시어 문제를 해결하여 사용자가 이런 문구를 보지 않길 바란다. (그렇지?)
그리고 sizefmt attribute가 반환하는 파일크기
형식을 config(설정)할 수 있다. 바이트로 크기를
보여주려면 bytes, 적절히 Kb나 Mb로 크기를
보여주려면 abbrev를 사용한다.
나는 다음 달에 작은 CGI 프로그램과 SSI를 같이 사용하는
글을 쓸 예정이다. 지금은 exec element로 할
수 있는 다른 것들을 설명할 것이다. SSI는 실제 쉘을 (정확히는
/bin/sh나 Win32를 사용한다면 DOS 쉘) 사용하여
명령어를 실행한다. 예를 들어, 다음은 디렉토리 목록을 보여준다.
<pre>
<!--#exec cmd="ls" -->
</pre>
or, on Windows
<pre>
<!--#exec cmd="dir" -->
</pre>
dir 출력에 브라우저가 혼동할
``<dir>'' 문자열이 포함되있기때문에,
윈도우즈에서 이 지시어를 사용하면 결과가 조금 이상할 것이다.
이 기능은 exec 태그에 사용한 어떤 명령어라도
실행할 수 있기때문에 매우 위험하다. ``방명록''과 같이 사용자가
웹페이지 내용을 수정할 수 있는 환경이라면, 이 기능을 절대로
사용해선 안된다. Options 지시어에
IncludesNOEXEC 아규먼트를 사용하여 SSI를 허용하지만
exec 기능을 막을 수 있다.
내용을 출력하는 기능 외에 아파치 SSI는 변수 설정이 가능하고, 비교문과 조건문에 이 변수를 사용할 수 있다.
이 글에서 설명하는 대부분의 기능은 아파치 1.2 이후부터 사용할 수 있다. 물론, 아파치 1.2 이상을 사용하지 않는다면 아마도 빨리 업그레이드해야 한다. 해라. 지금 해라. 기다릴 것이다.
set 지시어를 사용하여 나중에 사용할 변수를
설정할 수 있다. 앞으로 변수가 필요하기때문에 먼저 설명한다.
문법은 다음과 같다.
<!--#set var="name" value="Rich" -->
다음과 같이 값을 문자그대로 설정하지 않고 환경변수나 위에서 설명한 변수(예를
들어, LAST_MODIFIED)와 같이 다른 변수를 사용하여
변수값을 설정할 수도 있다. 이때 변수명 앞에 달러 표시($)를
붙여서 문자열이 아닌 변수임을 표시한다.
<!--#set var="modified" value="$LAST_MODIFIED" -->
변수값에 달러 문자를 그대로 입력하려면 달러 표시 앞에 백슬래쉬를 사용한다.
<!--#set var="cost" value="\$100" -->
마지막으로 긴 문자열 중간에 변수를 사용하는데 뒤에 있는 문자도 변수명으로 오인하여 혼동되는 경우, 변수명을 대괄호로 묶어서 확실히 한다. (좋은 예를 찾기 힘들지만, 무슨 말인지 이해하길 바란다.)
<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
변수를 설정하고 비교할 수 있으니 조건문이 가능하다. 이제
SSI가 일종의 간단한 프로그래밍언어가 된다.
mod_include는 조건문을 만드는 if,
elif, else, endif
구조를 제공한다. 실제 한 페이지로 여러 논리적인 페이지를
만들 수 있다.
조건문 구조는 다음과 같다.
<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->
test_condition에는 어떤 논리비교라도 사용할
수 있다. 값을 다른 값과 비교하거나, 특정 값이 ``참''인지
검사한다. (문자열이 비어있지 않으면 참이다.) 사용가능한
비교 연산자를 모두 보려면, mod_include
문서를 참고하라. 다음은 조건문을 사용한 몇가지 예제다.
설정파일에 다음 줄을 추가한다.
BrowserMatchNoCase macintosh Mac
BrowserMatchNoCase MSIE InternetExplorer
클라이언트가 맥킨토시에서 실행하는 Internet Explorer라면 환경변수 ``Mac''과 ``InternetExplorer'' 모두 참으로 설정한다.
그리고 SSI 문서에 다음과 같이 적는다.
<!--#if expr="${Mac} && ${InternetExplorer}" -->
여기에 사과문가 나온다
<!--#else -->
여기에 멋진 JavaScript 코드가 나온다
<!--#endif -->
내가 매킨토시 IE에 반감이 있는 것은 아니다. 나는 단지 저번주에 다른 곳에서는 문제가 없는 JavaScript 코드가 매킨토시 IE에서는 동작하지 않아서 몇시간을 고생했다. 위는 임시 해결책이다.
(직접 정의하였건 일반 환경변수이건) 어떤 변수라도 조건문에
사용할 수 있다. 아라치는 SetEnvIf나 다른 관련
지시어로 환경변수를 설정할 수 있기때문에 CGI 없이도 멋지게
동적인 내용을 만들 수 있다.
SSI는 확실히 CGI나 동적인 웹페이지를 생성하는 다른 기술을 대체할 수 없다. 그러나 많은 추가 작업없이 페이지에 동적인 내용을 조금 추가하기에는 훌륭한 방법이다.
�뀂X�,�\+홓撰X�l ~넾�_삀�U <
/CQ�徠�]�[(�!l턱5�#�w�]�9�"0@0t� �\ut半나?L�虞v�U躊狸s斜]X믆F��m♪
ㅄ50幷喪錐u�U�{X.�씄j0��5郊�1�?7s쾍��M駟뒨衒離� 콨�(�� � � =4�:]�徙� ?��_ _Q�㉰k�Re[� w�)`�=��6屈%國5@E施u멆-꼖x\bl⑹
`%^A蓄u�꽳�l�[-u.+�//ㅲ�M@u쁗)xs쁞흐�휻岳q0](�xxc눌[�y뇪|4爀2 쨢컗�Yㅬ�U쓖�#�a�F226�.���몙-H 흝ⅶ�
(e@ �z둾�귖i)O뼗9v@鰍n@5)�� 憶艙�-� 0�-�e�����2��3 �,X� 9lQ c�c(8�Q eP 2�.�땧쮥P�~(� 4�굗�툩g�� �3�-�y 3�(��V增�L�^�y�!�긪댼��V�� �2( 2��컗w8
P f� cP�
� *@5P2P�㈁f븧�0c� .���3��x@X긦� j(� 긏3
`
�.c� .x� 52P,W翎佾뉫�+@H�0僿꺘�]�f}xz � P�� 쮪
(눖갑gm. e�뇮�i(e0@�� ��bR ㉺�20�
0�2 g0 갚 P�xXk10�꼓#줰e긝F�-m原�BP눷�1K.L^浣�4�f}� @4젂~��i�쇶��.@ 묘kl *픥�굪�il�&�픡5@�2@c릥 (뇟냞@ 5���:3�Z � �k�%�꼝�`麴a�I枉>�j랴�-�.���: 고w�c늾�6�0냰��KJ�3릥 ���}� j@�d�e0 ⓩ
x쐖iŒ� ?듣吊~j�쥴쌲O`�'�꼟XoJm晸�f8*먲�:.� 4�+�
(}��5 *���0�*旣 +릥 #i0� 쟼�Q��?#쭍z� ㎺�f� 릐y�p � 3쮥�>?숫纓�놺 꾃}q$N욈� 븞X�&�~쮩�볩琶�b q��~H
AW y@뒉�A'4� G� @?E� �l �S4�|꾗}q엻q듛l쥔$b" _섆;뢢
\騶鱇{쁾멈kP�W司�L7'摺퉯O� O ^o� 쟜 ��8CD$>鷺W嵐�+Y0�Swv븆n磵�G+겳쐧3�]f恂Os솪-괳�h鷺櫚� 갅�4췙H�웺�쏑�썷 �!!�늤��nV몂M����/,퓧?꿖 �눆릚�)hk窄꺊�땧씒뀽輛W�Z�
(겈� 퍈#��d늽8肉@�� +��� jHr")
�yj(i(깢� c�5� �굲�-+8�젂골w 걑`iL."�i땏 Z晴b_쐘 �쵔�봑 ㄿ�-��~0�
0��p캢 jP�5 �~�곜�i��20j W 쯁 X3 괎y4(�w(��뎝踊(z�Pt쾁�(�>�~��T廛�g�ed�Q�@h{a�c 奴{�|g� ��~ �n뷥�����~0{+ ����2�f윅�W걒0� �p쏴
�궸8�� 煦~5� � 2�4� Xw1틌�!m^}V (hP�1
2l�p!폹�$娜�!��7r麟�#��"G�I-횇h%3궛琇��~�속W睾&�!쟣,�<낣D$�"�1�jn굅쉨j힣.�쥓�쟓策쬪 �d�(�/Y냭j*��a�?iH\\셇Y
睛帙疑/敾
0x0蔬~�lI!줳쎹��'S�倂J븕5�4c◆;V�q�웹�2 � 覓.C1h�輛칻i1螺�[냒Oy|�A"�2�z櫶 v좿꿝PQ孫m먬텲L�u/퍙�2浹萎/H�0 꼟披쏏dI죒篒蒼�잧IH#X I�U속�UXQ�2U쁐Fw�lQ�쑒�1e叭죨*sa�U�V삞O2T봓��tT�0ㅖ���캐��봓5b尖���唜^�%c�^�9�$��_|닏휁7�@紂!�D�%쁝:쟣b냊�~h싆�2L&�&쒒�� aT袈?� E��3g쐛
셾^Ts(즻24%|w뼱O1},�8�)�a&`㎕v붛M뒂*삉&)I�E|�2さ2�i숣��>�2챿�,뇬♥�윫뉄둑-D�5�: ª� ��4ㅄP<%`쨉괇SA @)濤⒰�+Y��:R>�Q 煤�.��}슔4�`[푔�sA�A낈�+lW팙��Cx摯�W숀H뫄홙Ax늫봨P�<渦 2� 5�nH湟�Dx2�?)즮qe툛Q 껗@뇢� メ┦Ik눠뺩��IK�b뤢J[띛I
X@P�'_訖zj昔�~�5�+�SN'BHm裙)W虧I<`BM鉉��<{惚w�� 멘{^멕悴춝��;��먮 9��?쓿�껾.y�뽯]��wIs칈g짳땾1���.��>팂'f 밸�;節畵;彫 ?<紬<卒�쏊젲端��@v� �;전!�쪘�<�O]P4뺗�?>緘�>顯タ엇 `v��]R;턑A� 쬡{3_�+ `퇦���< ㉯2컖| #댝�'H떉禾뿺븿�R`B!П r/@j @EB�,� 8C㈋턆u�C꺂� H棹%( �^3���:U
mI� (H蓴C읜#.|G쎧냐u��$�덍
s�l�_ ��뭂걗P좾^�
b��K냛촗E�o�AR�;빗F0�$낎5F�륂q$T � �p� ��Vq 1�0�(�b �hㅝ���*픠��1챥냵 �뱎뇟콺B (A
愍G M)D붶H!�릤e9볣�2깜�#A�*( a
糞�/{yヌ(�/훎^3�뤮#寀횩쥆�>jR쎔d�7
5�렪�P핢:쨔�}⒀쏊홟2횇�뭵 ��
v^Kc� /�쮙r$ 篩맆뎧�X�l(G�Q8t#�('샫'wL큋斐�C
�T⌒]8�H>���"��i㉯S�$
�3쓁I 6�{�b
E饅.�v�M�t�� !戾�邱TT#� 쳿�?�2えc�3⑷ㄶf� %B랫UCY빁" +{툓wpb^�@�T�㉡덱rEVNY�w�aE쁄<�xW8a&�@�Yk�>d 0zQ룯*V2 찫+K'+�-�!��:�
` S쿸븐MKi閔0�!咸��꿲Pv��y쮇敞F癖Ⅵ �="I>@F2돕k떰5Vㅾ뼴}卽B賂*�u첫a짯Q쿷]�@�C���S枇F 틽MTs�K믬b��=�>濾$仝T딘}n^O�~p뗿}딉}�c��27N�¶븍첈�륖 0I�둤�B�/彩�G� )A나p� S�굕$焚�-`늜븯=" )z[솩�뒆 쿾 �!-즵씿-뷢y =�a�#� E뙽 t�R���L듬d`�8$���d1�プ/if�