hosting

/usr/local/m2/setting.json 파일의 hosting 에 가상호스트를 구성하여 서비스한다. hosting[ ] 에서 삭제된 가상호스의 모든 자원은 삭제대상이 된다. 다시 추가해도 콘텐츠는 되살아나지 않는다.

가상호스트 개수에 제한은 없다.

{
  "hosting": [
      {
        "name": "www.foo.com",
        "enable": true,
        "listen": "*:80"
      },
      {
        "name": "www.bar.com",
        "aliases": [ "another.com", "*.sub.example.com" ]
      }
  ]
}

name

가상호스트 이름

enable (기본: true)

가상호스트 활성화

listen (기본: *:80)

{IP}:{Port} 형식으로 서비스 주소를 설정한다. 서비스 포트를 열지 않으려면 off 로 설정한다.

aliases

가상호스트 별명(alias) 리스트

mode

"mode": {
  "volatile": false,
  "facadeHost": null,
  "basehost": null
}

volatile (기본: false)

특정 가상호스트만 Memory-Only 모드 로 동작하도록 지정한다.

facadeHost (기본: null)

대상이 지정되어 있다면 이 가상호스트는 facade가상호스트가 되어 통계, 로그를 제외한 모든 HTTP 처리는 facadeHost 에 지정된 가상호스트에서 처리된다.

basehost

기반 가상호스트를 설정한다. hosting[ ] 내의 다른 가상호스트를 참조하거나 분리된 가상호스트 파일을 기반으로 한다.

Note

• basehost 로 지정/참조되는 가상호스트의 name 과 mode 설정을 제외하고 모두 가상호스트 설정으로 복제된다.

• basehost 를 사용/참조하는 가상호스트에 존재하는 명시적 설정은 basehost 보다 우선한다.

• 다른 가상호스트 설정을 기반으로 하는 경우

  {
    "hosting": [
      {
          "name": "foo.com"
          ...(생략)...
        },
        {
          "name": "bar.com",
          "mode": {
            "basehost": "www.foo.com"
          }
        }
      ]
  }
  

  bar.com 의 설정은 foo.com 의 모든 설정을 승계한 뒤 로딩된다.

• 파일로 분리된 가상호스트 설정을 기반으로 하는 경우

  {
    "hosting": [
      {
          "name": "foo.com"
          "mode": {
            "basehost": "/usr/local/m2/commons/hosting_image.json"
          }
        },
        {
          "name": "bar.com",
          "mode": {
            "basehost": "/usr/local/m2/commons/hosting_image.json"
          }
        }
      ]
  }
  

  foo.com , bar.com 은 /usr/local/m2/commons/hosting_image.json 설정을 승계한 뒤 로딩된다.

See also

• basehost 사용하기

origin

가상호스트는 원본서버를 대신해 콘텐츠를 서비스하는 것이 목적이다. 서비스 형태에 맞추어 다양한 원본서버 구성이 가능하다.

"origin": {
  "protocol": "http",
  "address": [ "10.10.10.10", "10.10.10.11" ],
  "address2": [ "10.10.10.20", "10.10.10.21" ]
}

protocol (기본: http)

원본 프로토콜. http 또는 https

address

원본주소 목록

address2

원본 보조주소 목록

Note

만약 원본서버가 인증이 필요한 AWS S3라면 authorization 설정을 추가한다.

예를 들어 다른 포트(8080)로 서비스되는 경우 1.1.1.1:8080과 같이 포트번호를 명시해야 한다. 주소는 {IP|Domain}{Port}{Path}형식으로 8가지 형식이 가능하다.

Address	Host헤더
1.1.1.1	가상호스트명
1.1.1.1:8080	가상호스트명:8080
1.1.1.1/account/dir	가상호스트명
1.1.1.1:8080/account/dir	가상호스트명:8080
example.com	example.com
example.com:8080	example.com:8080
example.com/account/dir	example.com
example.com:8080/account/dir	example.com:8080

host 헤더를 별도로 설정하지 않는한 표의 Host헤더를 전송한다.

{
  "hosting": [
    {
      "name": "www.foo.com",
      "origin": {
        "protocol": "http",
        "address": [ "origin.com:8888/account/dir" ]
      }
    }
  ]
}

예를 들어 위와같이 설정하고 GET / 로 요청하면 원본으로 다음과 같이 요청된다.

GET /account/dir HTTP/1.1
Host: origin.com:8888

원본서버에 example.com/account/dir 처럼 경로가 붙어있다면 요청된 URL은 원본서버 주소 경로 뒤에 붙는다. 클라이언트가 /img.jpg 를 요청하면 최종 주소는 example.com/account/dir/img.jpg 가 된다.

Note

AWS환경이라면 IP를 특정하지 않고 유동적인 인스턴스 목록 을 원본서버로 사용할 수 있다. env.management.aws. describeInstances 설정이 정의되어 있지 않다면 원본서버가 없는 것으로 간주한다.

urlRewrites

클라이언트 요청을 HTTP 표준에 맞추어 가상호스트로 라우팅하기 전 변조할 수 있다. 변조조건은 멀티로 설정할 수 있으며 순차적으로 정규표현식 일치 여부를 비교한다.

"urlRewrites" : [
  {
    "pattern": "$HEADER[cookie: *ILLEGAL*] & $URL[foo.com/([^/]+)/(.*)]",
    "replace": "www.example.com/#1.php?id=#2",
    "accessLogUrl": "replace"
  },
  {
    "pattern": "bar.com/(.*)?cache=on",
    "replace": "cache.example.com/#1",
    "accessLogUrl": "replace"
  }
]

Warning

pattern , replace 값 설정시 JSON 특수문자 처리에 주의한다.

특수문자	이스케이프 처리된 출력
따옴표 "	\"
백슬래시 \	\\
슬래시 /	\/
백스페이스	\b
폼 피드	\f
줄 바꿈	\n
캐리지 리턴	\r
가로 탭	\t

pattern

매칭시킬 패턴. 각 패턴은 $조건[값] 규칙을 사용하며, $URL[ ] 을 제외하고 부정표현(~이 아닌 경우)을 !조건[값] 형태로 지원한다.

Note

URL 을 제외한 나머지 조건으로만 설정을 구성 할 경우 replace 설정에 있는 문자열 그대로 전처리 된다.

• $URL[ ] HTTP 요청 URL을 정규표현식으로 검사/치환한다.

  Important

  • $URL 표현은 단 하나만 존재해야 한다.

  • !URL 부정표현은 지원되지 않는다.

• $URLMATCH[ ] HTTP 요청 URL을 정규표현식으로 검사한다. 부정표현을 지원한다. ( $URL[...] 과 $URLMATCH[...] 차이 참조)

• $IP[ ] IP, IP Range, Bitmask, Subnet 네 가지 형식을 지원한다. geoip 가 구성되어 있다면 국가코드를 값으로 사용할 수 있다.

• $HEADER[ ] HTTP 요청헤더 값을 검사한다. 값은 명확한 표현과 패턴을 인식한다. $HEADER[Key:] 처럼 구분자는 있지만 값이 빈 문자열이라면 요청 헤더의 값이 비어 있는 경우를 의미한다. $HEADER[Key] 처럼 구분자 없이 Key 만 명시되어 있다면 Key 에 해당하는 헤더의 존재유무를 조건으로 판단한다.

• $PROTOCOL[ ] HTTP 요청 프로토콜을 검사한다. 사용가능 값은 다음과 같으며 조건이 없는 경우 모든 프로토콜을 의미한다.

  • http

  • https

  • http2

• $FUNCTION[ ] HTTP 요청 URL에 함수호출이 존재하는지 검사한다. 부정표현을 지원한다.

  • * 함수호출이 하나라도 존재하는 경우

  • 함수이름 특정 함수가 호출되는 경우로 함수의 고유 이름을 입력한다. 예를 들어 dims 의 keyword 를 mydims 라는 키워드로 지정했어도 고유이름인 $FUNCTION[dims] 로 설정해야 한다.

    Note

    재정의된 함수 keyword 를 조건 설정하고 싶다면 $URLMATCH[ ] , $URL[ ] 조건을 사용할 것을 권장한다.

replace

변환형식을 설정한다. 일치된 패턴에 대해서는 #1, #2와 같이 사용할 수 있다. #0는 요청 URL전체를 의미한다. 패턴은 최대 9개(#9)까지 지정할 수 있다.

accessLogUrl

• replace 변경된 url을 access.log에 기록한다.

• pattern 클라이언트가 요청한 url을 access.log에 기록한다.

URL 전처리는 가상호스트 유입전에 동작되기 때문에 호스트 종합 통계에서 제공된다. 다음은 설정예제이다.

"urlRewrites" : [
  {
    # example.com/releasenotes/1.3.4 -> example.com/releasenotes.php?id=1.3.4
    "pattern": "example.com/([^/]+)/(.*)",
    "replace": "example.com/#1.php?id=#2"
  },
  {
    # example.com/download/1.3.4 -> download.example.com/1.3.4
    "pattern": "example.com/download/(.*)",
    "replace": "download.example.com/#1"
  },
  {
    # example.com/img/image.jpg?date=20140326 -> example.com/image.jpg?date=20140326/m2dims/composite/watermark1
    "pattern": "example.com/img/(.*\\.(jpg|png).*)",
    "replace": "example.com/#1/m2dims/composite/watermark1"
  },
  {
    # example.com/preview/audio.m4a -> example.com/audio.m4a?end=30&boost=10&bandwidth=2000&ratio=100
    "pattern": "example.com/preview/(.*)\\.(mp3|mp4|m4a)$",
    "replace": "example.com/#1.#2?&end=30&boost=10&bandwidth=2000&ratio=100"
  },
  {
    # example.com/video.mp4.m3u8 -> example.com/video.mp4/mp4hls/index.m3u8
    "pattern": "example.com/(.*)\\.mp4\\.m3u8$",
    "replace": "example.com/#1.mp4/mp4hls/index.m3u8"
  },
  {
    # example.com/video.mp4_10_20 -> example.com/example.com/video.mp4_10_20/video.mp4/10/20
    "pattern": "example.com/(.*)_(.*)_(.*)",
    "replace": "example.com/#0/#1/#2/#3
  }
]

Note

다음처럼 유사한 서브도메인이 있는 경우 주의해야 한다.

image.example.com
myimage.example.com

정규표현식에서는 image.exampe.com으로 패턴을 생성한 경우 myimage.example.com도 패턴과 일치하는 것으로 간주된다. 이를 방지하기 위해 맨 앞에 글자없음을 ^ 로 표기해주어야 image.example.com만 매칭시킬 수 있다.

{
  # example.com/video.mp4_10_20 -> example.com/example.com/video.mp4_10_20/video.mp4/10/20
  "pattern": "^image.example.com/img/(.*\\.(jpg|png).*)",
  "replace": "image.example.com/#1/m2/composite/watermark1"
}

Warning

최대 라우팅 개수는 10회이다.

fallbacks

원본서버 응답코드에 따라 해당 HTTP 트랜잭션의 fallback 정책을 구성한다. 응답코드, 요청헤더, 요청 URL, 응답 헤더를 결합조건으로 필터링 가능하다.

"fallbacks" : {
  "enable": false,
  "matchingList": [
    {
      "phase": "frontend",
      "resCodes": [ "500", "503", "504" ],
      "pattern": "$HEADER[user-agent: *IE6*] & $URL[/html/(.*)]",
      "replace": "/html/#1"
    },
    {
      "phase": "backend",
      "resCodes": [ "4xx" ],
      "pattern": "$URL[/(.*)]",
      "replace": "old.video.com/#1"
    },
    {
      "resCodes": [ "4xx" ],
      "pattern": "$URL[/(.*)] & $RESHEADER[Content-Type: text/html]",
      "replace": "sorry.example.com/#1",
      "serviceCode": "#LAST"
    }
  ]
}

enable (기본: false)

fallback 기능활성화

matchingList

매칭 리스트

phase (기본: frontend)

fallback 동작 시점.

• frontend (기본) 클라이언트(엔드 유저) 트랜잭션의 응답시점.

• backend 원본 캐싱 콘텐츠 응답시점 시점으로 함수체인 동작 상황에서 원본을 Fail-Over하기 위한 용도로 사용.

resCodes

설정가능한 항목은 아래와 같다.

• 404 등 명확한 HTTP 응답코드

• 1xx , 2xx , 3xx , 4xx , 5xx 같은 HTTP 응답코드 패턴

• fail 원본 연결/트랜잭션 실패

pattern

요청 패턴

표현	설명
$URL[...]	요청 URL
$URLMATCH[...]	요청 URL ( $URL[...] 과 $URLMATCH[...] 차이 참조)
$HEADER[...]	요청 헤더
$RESHEADER[...]	응답 헤더

이상의 조건을 키워드로 결합( & )할 수 있다.

Warning

캐싱 안정성을 위해 $RESHEADER[...] 는 선별적으로 헤더를 지원한다.

헤더	지원여부
Accept-Ranges	미지원
Connection	미지원
Content-Length	미지원
Date	미지원
Keep-Alive	미지원
Vary	미지원
Cache-Control	기본지원
Content-Disposition	기본지원
Content-Encoding	기본지원
Content-Type	기본지원
ETag	기본지원
Expire	기본지원
Last-Modified	기본지원
Location	기본지원
Server	기본지원
Transfer-Encoding	기본지원
Content-Language	cacheOriginal 활성화시 지원
Content-Location	cacheOriginal 활성화시 지원
Content-MD5	cacheOriginal 활성화시 지원
Proxy-Authenticate	cacheOriginal 활성화시 지원
Retry-After	cacheOriginal 활성화시 지원
TE	cacheOriginal 활성화시 지원
Trailer	cacheOriginal 활성화시 지원
Warning	cacheOriginal 활성화시 지원
WWW-Authenticate	cacheOriginal 활성화시 지원
Set-Cookie 및 커스텀 헤더	bypass 가 instant 모드로 동작할 때

replace

변조할 URL 패턴. host 가 없다면 같은 가상호스트로로 라우팅된다.

Note

URL을 변조없이 다른 가상호스트로만 라우팅하고 싶더라도 패턴매칭이 이루어져야 하므로 아래와 같이 표현해야 한다.

"pattern": "/(.*)",
"replace": "old.video.com/#1"

replace

변조할 URL 패턴. host 가 없다면 같은 가상호스트로로 라우팅된다.

serviceCode (기본: #LAST)

더 이상 fallback되지 않고 클라이언트에게 응답을 전송해야 하는 시점의 응답코드를 결정한다.

Warning

아래 응답코드가 결정된 상황에서는 동작하지 않는다.

• 204 No Content

• 206 Partial Content

• 304 Not Modified

• #FIRST 최초 응답코드

• #BEFORE (연쇄적으로 fallback되는 상황에서) 이전 요청의 응답코드

• #LAST (기본) 마지막 요청의 응답코드

• 숫자 응답코드를 특정 숫자로 고정한다. 예를 들어 403 으로 설정한다면 403 FORBIDDEN 으로 응답한다. 100 번대, 206 , 300 번대 코드는 설정할 수 없다.

fallback으로 redirect하기

fallback 시점에 클라이언트를 Redirect 시키려면 accessControl 을 이용한 트릭이 필요하다. 다음은 proxy 함수의 원본 트랜잭션이 실패하는 경우 500 에러 대신 원본주소를 클라이언트에게 302 응답하는 예제이다.

1. proxy 함수 규칙 실패시 URL에 임의의 규칙을 추가하여 fallback 시킨다.

     # hosting[].fallbacks.matchingList
     # /_fallback_redirect_/ 는 임의의 문자열일뿐 아무 의미를 가지지 않는다.
   
     {
       "resCodes": [ "fail" ],
       "pattern": "/proxy/src/(.*)",
       "replace": "/_fallback_redirect_/#1"
   }
   

   /proxy/src/https://foo.com/sample.jpg 요청이 /_fallback_redirect_/https://foo.com/sample.jpg 으로 변경되어 다시 라우팅된다.

2. accessControl 에서 /_fallback_redirect_/* 패턴을 Redirect 시킨다.

   # network.http.frontEnd.accessControl.matchingList
   
   {
     "pattern": "$URL[/_fallback_redirect_/*]",
     "action": "redirect",
     "location": "#1"
   }
   

   클라이언트는 https://foo.com/sample.jpg 로 redirect 로 된다.

https

별도의 IP 또는 포트를 지정하지 않는 경우 기본으로 바인딩되는 서비스 주소는 *:443 이다.

"https" : [
  {
    "cert" : "/usr/ssl/cert.pem",
    "key" : "/usr/ssl/certkey.pem",
    "ca" : "/usr/ssl/CA.pem"
  }
]

Note

인증서 포맷은 PEM(Privacy Enhanced Mail), 비대칭키 알고리즘은 RSA만 지원한다.

cert

서비스 인증서 경로 또는 URL

key

인증서 개인키 (암호화 해제상태) 경로 또는 URL

ca

CA 인증서 체인 경로 또는 URL

options

"options": {
  "listen" : "*:443",
  "enableTls13": false,
  "enableTls12": true,
  "enableTls11": true,
  "enableTls10": false,
  "enableSsl30": false,
  "ciphersuite" : "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP",
  "forwardSecrecy": true
}

listen (기본: *:443)

HTTPS 서비스 IP:Port 또는 NIC 이름.

Note

같은 Port를 서비스하더라도 보다 명확한 표현이 우선한다. 예를 들어 위 NIC가 3개이고 각각의 IP가 1.1.1.1, 1.1.1.2, 1.1.1.3인 경우를 가정해 보자. 1.1.1.1:443 으로 접속한 클라이언트는 가장 명시적 표현인 2번째 "listen": "1.1.1.1:443" 인증서로 서비스된다. 반면 1.1.1.3:443 으로 접속한 클라이언트는 IP가 일치하는 1번째 "listen": "*:443" 인증서로 서비스된다. 인증서파일을 같은 이름으로 덮어쓰기 하여도 Reload할 때 반영된다.

enableTls13 (기본: false)

TLS v1.3 활성화

enableTls12 (기본: true)

TLS v1.2 활성화

enableTls11 (기본: true)

TLS v1.1 활성화

enableTls10 (기본: false)

TLS v1.0 활성화

enableSsl30 (기본: false)

SSL v3.0 활성화

ciphersuite

Cipher-Suite 선택옵션. Apache mod_ssl의 SSL CipherSuite표현 을 따른다.

forwardSecrecy (기본: true)

• true (기본) - Forward Secrecy를 보장하는 CipherSuite를 우선적으로 선택한다.

• false - ClientHello에 명시된 순서대로 선택한다.

Note

Forward Secrecy 를 보장하면 더 높은 보안성을 얻을 수 있다. (아래 링크 참조)

• SSL Labs: Deploying Forward Secrecy

• SSL/TLS & Perfect Forward Secrecy

• Configuring Apache, Nginx, and OpenSSL for Forward Secrecy

functions

다음과 같이 루트의 functions 설정은 모든 가상호스트의 기본 설정으로 동작한다. 만약 설정되어 있지 않다면 기본 값으로 동작한다.

{
  "functions": {
    ...
}

functions 의 모든 기능을 특정 가상호스트에서만 설정하고 싶다면 가상호스트 하위에 설정한다.

{
  "hosting": [
    {
      "name": "www.foo.com",
      "functions": {
        ...
      }
  ]
}

hook

"hook": {
  "enable": false,
  "path": "https://example.com/sample.js",
  "matchingList": null,
  "session": { }
}

enable (기본: false)

hooking을 활성화한다.

path

Hook 경로

matchingList

매칭 리스트. 설정되어 있지 않다면 모든 요청에 대해 hook을 수행한다.

"matchingList": [
  {
    "pattern": "$HEADER[cookie: *ILLEGAL*] & $URL[/([^/]+)/(.*)]"
  },
  {
    "pattern": "/(.*)?cache=on"
  }
]

pattern

요청 패턴. urlRewrites 의 pattern 과 동일하지만 가상호스트 이름을 명시하지 않는다.

session

"session":{
  "connectTimeout": 3,
  "receiveTimeout": 3,
  "reuseTimeout": 60,
  "param": null
}

connectTimeout (기본: 3)

Hook 모듈 연결 타임아웃

receiveTimeout (기본: 3)

Hook 모듈 수신 타임아웃

reuseTimeout (기본: 60)

Hook 모듈세션 재사용 타임아웃

param (기본: null)

Hook 모듈로 전달할 설정 직렬화된 escaped JSON

AWS Signed Cookie 복호화

내장된 Hook을 통해 AWS Signed Cookie 복호화 기능을 지원한다.

"hook": {
  "enable": true,
  "name": "@aws_cf_otu",
  "session": {
      "param": {
          "PublicKey": "/var/temp/public_key.pem"
      }
  }

}