apache/docs/manual/howto/ssi.xml.ko

<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
<!-- English Revision: 420990 -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

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

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

<manualpage metafile="ssi.xml.meta">
<parentdocument href="./">How-To / Tutorials</parentdocument>

<title>아파치 투토리얼: Server Side Includes 소개</title>

<summary>
<p>Server-side includes를 사용하여 HTML 문서에 동적인 내용을
추가할 수 있다.</p>
</summary>

<section id="related"><title>소개</title>
 <related>
    <modulelist>
    <module>mod_include</module>
    <module>mod_cgi</module>
    <module>mod_expires</module>
    </modulelist>

    <directivelist>
    <directive module="core">Options</directive>
    <directive module="mod_include">XBitHack</directive>
    <directive module="mod_mime">AddType</directive>
    <directive module="core">SetOutputFilter</directive>
    <directive module="mod_setenvif">BrowserMatchNoCase</directive>
    </directivelist>
</related>

    <p>이 글은 보통 SSI라고 부르는 Server Side Includes를 설명한다.
    SSI가 가능하도록 서버를 설정하는 방법과 HTML 페이지에 동적인
    내용을 추가하는 기본적인 SSI 사용법을 소개한다.</p>

    <p>이 글의 뒷부분은 SSI 지시어 조건문과 같은 고급기법을
    설명한다.</p>

</section>

<section id="what"><title>SSI가 무엇인가?</title>

    <p>SSI (Server Side Includes)는 HTML 페이지에 사용하는 지시어로,
    페이지를 서비스할때 서버가 처리한다. SSI를 사용하면 CGI
    프로그램이나 다른 동적인 기술로 페이지 전체를 만들어서
    서비스하지 않고도 HTML 페이지에 동적으로 생성한 내용을 추가할
    수 있다.</p>

    <p>SSI를 사용할지 아니면 프로그램으로 페이지 전체를 생성할지
    결정은 페이지에서 정적인 부분이 많은지와 페이지를 서비스할
    때마다 어느정도를 다시 계산해야할지에 달렸다. SSI는 현재
    시간과 같이 적은 정보를 추가하는데 좋다. 그러나 페이지를
    서비스할때 페이지의 대부분을 생성해야 한다면 다른 방법을
    찾아봐야 한다.</p>
</section>

<section id="configuring">
<title>SSI가 가능하도록 서버 설정하기</title>

    <p>서버가 SSI를 처리하려면 <code>httpd.conf</code> 파일이나
    <code>.htaccess</code> 파일에서 다음 지시어를 사용해야 한다.</p>
<example>
        Options +Includes
</example>

    <p>그러면 아파치는 파일에서 SSI 지시어를 처리한다. 설정에는
    보통 여러 <directive module="core">Options</directive> 지시어가
    있고, 이 지시어들은 서로 덮어써서 무효로 만들다. 그래서
    지시어를 맨마지막에 처리하기위해 보통 SSI를 원하는 특정
    디렉토리에서 <code>Options</code>를 사용한다.</p>

    <p>모든 파일에서 SSI 지시어를 처리하는 것은 아니다. 아파치에게
    어떤 파일을 처리할지 알려줘야 한다. 두가지 방법이 있다.
    하나는 다음과 같은 지시어로 <code>.shtml</code>과 같은 특정
    파일 확장자를 가진 파일을 처리하는 방법이다.</p>
<example>
        AddType text/html .shtml<br />
	AddOutputFilter INCLUDES .shtml
</example>

    <p>이 방법의 단점은 이미 있는 페이지에 SSI 지시어를 추가하는
    경우 SSI 지시어를 처리하기위해 <code>.shtml</code> 확장자를
    부여하기때문에 파일명과 이 페이지의 모든 링크를 변경해야
    하는 점이다.</p>

    <p>다른 방법은 <directive module="mod_include">XBitHack</directive>
    지시어를 사용하는 방법이다.</p>
<example>
        XBitHack on
</example>

    <p><directive module="mod_include">XBitHack</directive>는
    실행권한이 있는 파일에서 SSI 지시어를 처리한다. 그래서 이미
    있는 페이지에 SSI 지시어를 추가한다면 파일명을 변경하지
    않고 <code>chmod</code>로 파일에 실행권한을 주면 된다.</p>
<example>
        chmod +x pagename.html
</example>

    <p>하지 말아야 할 것 하나. 가끔 <code>.shtml</code> 파일명에
    골치를 앓지말고 모든 <code>.html</code> 파일을 SSI 처리하라고
    충고하는 사람이 있다. 이 사람들은 아마도 <directive
    module="mod_include">XBitHack</directive>에 대해 모르는
    것 같다. 명심할 점은 이렇게 하면 아파치는 파일에 SSI 지시어가
    없더라도 클라이언트로 보내는 모든 파일을 살펴봐야 한다는
    것이다. 성능이 매우 느려질 수 있으며, 좋은 생각이 아니다.</p>

    <p>물론 윈도우즈에서는 실행권한이란 것이 없기때문에 후자를
    사용할 수 없다.</p>

    <p>내용이 동적이여서 계산하기 어렵기때문에 아파치 기본 설정은
    SSI 페이지의 최근수정일과 content length HTTP 헤더를 보내지
    않는다. 그래서 문서를 캐쉬하지 못하고 클라이언트가 느끼는
    성능이 떨어진다. 두가지 해결방법이 있다.</p>

    <ol>
      <li><code>XBitHack Full</code> 설정은 사용한다. 그러면
      아파치는 포함하는(include) 파일들의 수정일은 무시한체
      원래 요청한 파일의 날짜만 보고 최근수정일을 알아낸다.</li>

      <li><module>mod_expires</module>에 있는 지시어를 사용하여
      파일에 직접 만기일을 설정하면 브라우저와 프록시가 문서를
      캐쉬할 수 있다.</li>
    </ol>
</section>

<section id="basic"><title>기본 SSI 지시어</title>

    <p>SSI 지시어의 사용법은 다음과 같다.</p>
<example>
        &lt;!--#element attribute=value attribute=value ... --&gt;
</example>

    <p>HTML 주석같이 생겼기때문에 SSI 기능을 가동하지 않아도
    HTML 소스에는 나오지만 브라우저는 무시한다. SSI를 올바로
    설정하면 지시어를 결과값으로 바꾼다.</p>

    <p>element는 다음중 하나다. 다음 회에 더 자세히 설명할 것이다.
    지금은 SSI로 할 수 있는 몇가지 예를 보인다</p>

<section id="todaysdate"><title>오늘 날짜</title>

<example>
        &lt;!--#echo var="DATE_LOCAL" --&gt;
</example>

    <p><code>echo</code> element는 변수값을 그대로 출력한다.
    CGI 프로그램에 제공하는 환경변수들 외에도 여러 표준 변수가
    있다. 또, <code>set</code> element를 사용하여 직접 변수를
    정의할 수도 있다.</p>

    <p>날짜 출력 형식이 마음에 들지 않는다면, 다음과 같이
    <code>config</code> element의 <code>timefmt</code> attribute를
    사용한다.</p>

<example>
        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;<br />
        Today is &lt;!--#echo var="DATE_LOCAL" --&gt;
</example>
</section>

<section id="lastmodified"><title>파일의 수정일</title>

<example>
        이 문서는 &lt;!--#flastmod file="index.html" --&gt;에 마지막으로 수정되었다
</example>

    <p>이 element도 <code>timefmt</code> 형식 설정에 달렸다.</p>
</section>

<section id="cgi"><title>CGI 프로그램 결과를 포함하기</title>

    <p>일반적인 SSI 사용법중 하나로, 많이들 애용하는 ``방문수
    카운터'' 같은 CGI 프로그램 결과를 출력한다.</p>

<example>
        &lt;!--#include virtual="/cgi-bin/counter.pl" --&gt;
</example>

</section>
</section>

<section id="additionalexamples">
<title>추가 예제</title>

    <p>다음은 HTML 문서에 사용할 수 있는 몇가지 SSI 예제다.</p>

<section id="docmodified"><title>이 문서가 언제 마지막으로
수정되었나?</title>

    <p>앞에서 SSI를 사용하여 사용자에게 문서의 최근수정일을
    알릴 수 있다고 말했다. 그러나 실제 방법은 알려주지 않았다.
    다음 코드를 HTML 문서에 사용하면 페이지에 시간 기록을 남긴다.
    물론 위에서 설명한대로 SSI가 올바로 작동해야 한다.</p>
<example>
        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;<br />
        이 문서는 &lt;!--#flastmod file="ssi.shtml" --&gt;에 마지막으로 수정되었다;
</example>

    <p>물론 <code>ssi.shtml</code>대신 원하는 실제 파일명을
    사용한다. 아무 페이지에라도 붙여넣을 수 있는 범용코드를
    원한다면, 파일명 대신 <code>LAST_MODIFIED</code> 변수를
    사용한다.</p>
<example>
        &lt;!--#config timefmt="%D" --&gt;<br />
        This file last modified &lt;!--#echo var="LAST_MODIFIED" --&gt;
</example>

    <p><code>timefmt</code> 형식에 대한 자세한 정보는 검색엔진에서
    <code>strftime</code>을 찾아봐라. 문법은 같다.</p>
</section>

<section id="standard-footer">
<title>표준 페이지 하단을 포함하기</title>

    <p>여러 페이지가 있는 사이트를 관리한다면 페이지 전체를
    수정하는 것은, 특히 페이지들이 표준 외관을 가지도록 수정하는
    것은 정말로 괴롭다.</p>

    <p>페이지 상단(header)과 하단(footer)을 파일로 포함하여
    이런 수정의 부담을 덜 수 있다. 모든 페이지에서
    <code>include</code> SSI 명령어를 사용하여 페이지 하단 파일
    하나를 포함하면 된다. <code>include</code> element의
    <code>file</code> attribute나 <code>virtual</code> attribute로
    포함할 파일을 지정한다. <code>file</code> attribute는 <em>현재
    디렉토리에 상대적인</em> 파일경로다. 즉, (/로 시작하는)
    절대파일경로나 경로 안에 ../를 사용할 수 없다. 아마도 서비스하는
    문서의 상대 URL을 지정할 수 있는 <code>virtual</code> attribute가
    더 유용할 것이다. 경로를 /로 시작할 수 있지만, 포함하려는
    파일이 서비스하는 파일과 같은 서버에 있어야 한다.</p>
<example>
        &lt;!--#include virtual="/footer.html" --&gt;
</example>

    <p>나는 보통 이 두가지를 합쳐서 포함할 페이지 하단 파일에
    <code>LAST_MODIFIED</code> 지시어를 넣는다. 포함하려는 파일에도
    SSI 지시어가 나올 수 있으며, 이렇게 포함한 파일이 다른 파일을
    포함하는 식으로 여러번 계속 포함할 수도 있다.</p>
</section>

</section>

<section id="config">
<title>이외에 설정할 수 있는 것은?</title>

    <p>시간 형식 <code>config</code>(설정) 외에 두가지를 더
    <code>config</code>(설정)할 수 있다.</p>

    <p>보통 SSI 지시어가 잘못되면 다음과 같은 문구가 나온다</p>
<example>
        [an error occurred while processing this directive]
</example>

    <p>이 문구를 변경하고 싶다면 <code>config</code> element의
    <code>errmsg</code> attribute를 사용하여 변경한다.</p>
<example>
        &lt;!--#config errmsg="[It appears that you don't know how to use SSI]" --&gt;
</example>

    <p>사이트를 서비스하기 전에 모든 SSI 지시어 문제를 해결하여
    사용자가 이런 문구를 보지 않길 바란다. (그렇지?)</p>

    <p>그리고 <code>sizefmt</code> attribute가 반환하는 파일크기
    형식을 <code>config</code>(설정)할 수 있다. 바이트로 크기를
    보여주려면 <code>bytes</code>, 적절히 Kb나 Mb로 크기를
    보여주려면 <code>abbrev</code>를 사용한다.</p>
    </section>

<section id="exec">
    <title>명령어 실행하기</title>

    <p>나는 다음 달에 작은 CGI 프로그램과 SSI를 같이 사용하는
    글을 쓸 예정이다. 지금은 <code>exec</code> element로 할
    수 있는 다른 것들을 설명할 것이다. SSI는 실제 쉘을 (정확히는
    <code>/bin/sh</code>나 Win32를 사용한다면 DOS 쉘) 사용하여
    명령어를 실행한다. 예를 들어, 다음은 디렉토리 목록을 보여준다.</p>
<example>
        &lt;pre&gt;<br />
        &lt;!--#exec cmd="ls" --&gt;<br />
        &lt;/pre&gt;
</example>

    <p>or, on Windows</p>
<example>
        &lt;pre&gt;<br />
        &lt;!--#exec cmd="dir" --&gt;<br />
        &lt;/pre&gt;
</example>

    <p><code>dir</code> 출력에 브라우저가 혼동할
    ``&lt;<code>dir</code>&gt;'' 문자열이 포함되있기때문에,
    윈도우즈에서 이 지시어를 사용하면 결과가 조금 이상할 것이다.</p>

    <p>이 기능은 <code>exec</code> 태그에 사용한 어떤 명령어라도
    실행할 수 있기때문에 매우 위험하다. ``방명록''과 같이 사용자가
    웹페이지 내용을 수정할 수 있는 환경이라면, 이 기능을 절대로
    사용해선 안된다. <code>Options</code> 지시어에
    <code>IncludesNOEXEC</code> 아규먼트를 사용하여 SSI를 허용하지만
    <code>exec</code> 기능을 막을 수 있다.</p> 
    </section>

<section id="advanced">
<title>고급 SSI 기법</title>

    <p>내용을 출력하는 기능 외에 아파치 SSI는 변수 설정이 가능하고,
    비교문과 조건문에 이 변수를 사용할 수 있다.</p>

<section id="caveat"><title>경고</title>

    <p>이 글에서 설명하는 대부분의 기능은 아파치 1.2 이후부터
    사용할 수 있다. 물론, 아파치 1.2 이상을 사용하지 않는다면
    아마도 빨리 업그레이드해야 한다. 해라. 지금 해라. 기다릴
    것이다.</p>
</section>

<section id="variables"><title>변수 설정</title>

    <p><code>set</code> 지시어를 사용하여 나중에 사용할 변수를
    설정할 수 있다. 앞으로 변수가 필요하기때문에 먼저 설명한다.
    문법은 다음과 같다.</p>
<example>
        &lt;!--#set var="name" value="Rich" --&gt;
</example>

    <p>다음과 같이 값을 문자그대로 설정하지 않고 <a
    href="../env.html">환경변수</a>나 위에서 설명한 변수(예를
    들어, <code>LAST_MODIFIED</code>)와 같이 다른 변수를 사용하여
    변수값을 설정할 수도 있다. 이때 변수명 앞에 달러 표시($)를
    붙여서 문자열이 아닌 변수임을 표시한다.</p>

    <example> &lt;!--#set var="modified" value="$LAST_MODIFIED" --&gt;
    </example>

    <p>변수값에 달러 문자를 그대로 입력하려면 달러 표시 앞에
    백슬래쉬를 사용한다.</p>
<example>
        &lt;!--#set var="cost" value="\$100" --&gt;
</example>

    <p>마지막으로 긴 문자열 중간에 변수를 사용하는데 뒤에 있는
    문자도 변수명으로 오인하여 혼동되는 경우, 변수명을 대괄호로
    묶어서 확실히 한다. (좋은 예를 찾기 힘들지만, 무슨 말인지
    이해하길 바란다.)</p>
<example>
        &lt;!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --&gt;
</example>
</section>

<section id="conditional">
<title>조건 표현식</title>

    <p>변수를 설정하고 비교할 수 있으니 조건문이 가능하다. 이제
    SSI가 일종의 간단한 프로그래밍언어가 된다.
    <module>mod_include</module>는 조건문을 만드는 <code>if</code>,
    <code>elif</code>, <code>else</code>, <code>endif</code>
    구조를 제공한다. 실제 한 페이지로 여러 논리적인 페이지를
    만들 수 있다.</p>

    <p>조건문 구조는 다음과 같다.</p>
<example>
    &lt;!--#if expr="test_condition" --&gt;<br />
    &lt;!--#elif expr="test_condition" --&gt;<br />
    &lt;!--#else --&gt;<br />
    &lt;!--#endif --&gt;
</example>

    <p><em>test_condition</em>에는 어떤 논리비교라도 사용할
    수 있다. 값을 다른 값과 비교하거나, 특정 값이 ``참''인지
    검사한다. (문자열이 비어있지 않으면 참이다.) 사용가능한
    비교 연산자를 모두 보려면, <module>mod_include</module>
    문서를 참고하라. 다음은 조건문을 사용한 몇가지 예제다.</p>

    <p>설정파일에 다음 줄을 추가한다.</p>
<example>
        BrowserMatchNoCase macintosh Mac<br />
        BrowserMatchNoCase MSIE InternetExplorer
</example>

    <p>클라이언트가 맥킨토시에서 실행하는 Internet Explorer라면
    환경변수 ``Mac''과 ``InternetExplorer'' 모두 참으로 설정한다.</p>

    <p>그리고 SSI 문서에 다음과 같이 적는다.</p>
<example>
        &lt;!--#if expr="${Mac} &amp;&amp; ${InternetExplorer}" --&gt;<br />
        여기에 사과문가 나온다<br />
        &lt;!--#else --&gt;<br />
        여기에 멋진 JavaScript 코드가 나온다<br />
        &lt;!--#endif --&gt;
</example>

    <p>내가 매킨토시 IE에 반감이 있는 것은 아니다. 나는 단지
    저번주에 다른 곳에서는 문제가 없는 JavaScript 코드가 매킨토시
    IE에서는 동작하지 않아서 몇시간을 고생했다. 위는 임시
    해결책이다.</p>

    <p>(직접 정의하였건 일반 환경변수이건) 어떤 변수라도 조건문에
    사용할 수 있다. 아라치는 <code>SetEnvIf</code>나 다른 관련
    지시어로 환경변수를 설정할 수 있기때문에 CGI 없이도 멋지게
    동적인 내용을 만들 수 있다.</p>
</section>
</section>

<section id="conclusion"><title>결론</title>

    <p>SSI는 확실히 CGI나 동적인 웹페이지를 생성하는 다른 기술을
    대체할 수 없다. 그러나 많은 추가 작업없이 페이지에 동적인
    내용을 조금 추가하기에는 훌륭한 방법이다.</p>
</section>

</manualpage>