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 설정을 승계한 뒤 로딩된다.

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 deprecated 설정을 추가한다.

예를 들어 다른 포트(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 가 된다.

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 응답하는 예제이다.

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 으로 변경되어 다시 라우팅된다.

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

hosting¶

mode¶

origin¶

urlRewrites¶

fallbacks¶

fallback으로 redirect하기¶

https¶

options¶

functions¶

hook¶

session¶

AWS Signed Cookie 복호화¶