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
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또는httpsaddress원본주소 목록
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. ref-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 특수문자 처리에 주의한다.
특수문자 |
이스케이프 처리된 출력 |
|---|---|
따옴표 |
|
백슬래시 |
|
슬래시 |
|
백스페이스 |
|
폼 피드 |
|
줄 바꿈 |
|
캐리지 리턴 |
|
가로 탭 |
|
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 요청 프로토콜을 검사한다. 사용가능 값은 다음과 같으며 조건이 없는 경우 모든 프로토콜을 의미한다.httphttpshttp2
$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-LanguagecacheOriginal 활성화시 지원
Content-LocationcacheOriginal 활성화시 지원
Content-MD5cacheOriginal 활성화시 지원
Proxy-AuthenticatecacheOriginal 활성화시 지원
Retry-AftercacheOriginal 활성화시 지원
TEcacheOriginal 활성화시 지원
TrailercacheOriginal 활성화시 지원
WarningcacheOriginal 활성화시 지원
WWW-AuthenticatecacheOriginal 활성화시 지원
Set-Cookie및 커스텀 헤더bypass 가
instant모드로 동작할 때replace변조할 URL 패턴.
host가 없다면 같은 가상호스트로로 라우팅된다.Note
URL을 변조없이 다른 가상호스트로만 라우팅하고 싶더라도 패턴매칭이 이루어져야 하므로 아래와 같이 표현해야 한다.
"pattern": "/(.*)", "replace": "old.video.com/#1"
replace변조할 URL 패턴.
host가 없다면 같은 가상호스트로로 라우팅된다.serviceCode (기본: #LAST)더 이상 fallback되지 않고 클라이언트에게 응답을 전송해야 하는 시점의 응답코드를 결정한다.
Warning
아래 응답코드가 결정된 상황에서는 동작하지 않는다.
204 No Content206 Partial Content304 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
caCA 인증서 체인 경로 또는 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 활성화
ciphersuiteCipher-Suite 선택옵션. Apache mod_ssl의 SSL CipherSuite표현 을 따른다.
forwardSecrecy (기본: true)
true (기본)- Forward Secrecy를 보장하는 CipherSuite를 우선적으로 선택한다.
false- ClientHello에 명시된 순서대로 선택한다.
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을 활성화한다.
pathHook 경로
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