ATS配置文件remap.config解读

在加深对remap.config的配置用法时，我阅读了参考文献[1],特梳理如下：


remap.config文件默认存放在/usr/local/etc/trafficserver/下面，包含ATS需要用到的如下映射规则mapping rules
a.当ATS充当某源站的反向代理时，将对该源站的URL request映射到ATS上的某个location上;
b.当源站对带有location header的请求响应时，反向映射server location header，使之到ATS上;
c.永久或是暂时重定向HTTP request，否则没有ATS的话，它们会连接某个源站;


关于重定向HTTP request和使用反向代理，参考Reverse Proxy and HTTP Redirects。
当你修改了remap.config后，使用traffic_line -x来使之生效。当你在集群中的一个节点上使变化生效了，ATS会同步配置修改，自动将对集群中的其他节点生效。


格式
remap.config中的每行必须包含一个映射规则mapping rules，以#开头的行被忽略。为了便于阅读，每行可以分成多行，并使用\来连接
ATS识别3种空格分隔的域:type, target和replacement，下面描述每种域的格式
type
target
replacement


优先级
remap rules不会从上到下处理，而是基于一定的内部优先级。一旦这些规则被执行，我只取在配置文件解析顺序中的首个匹配：
map_with_recv_port and `regex_map_with_recv_port`
map and regex_map and reverse_map
redirect and redirect_temporary
regex_redirect and regex_redirect_temporary


Match-All
map rule中的单个/视作一个通配符，它匹配任意请求，注意小心使用，当然在remap.config文件末尾只能使用一次，比如
map / http://all.example.com


例子
下面几节给出remap.config文件中的mapping rules例子


反向代理映射例子
下面的例子在target和replacement中没有给出path前缀
map http://www.x.com/ http://server.hoster.com/
reverse_map http://server.hoster.com/ http://www.x.com/
这个例子导致下面的转换
    Client Request                            Translated Request
http://www.x.com/Widgets/index.html            http://server.hoster.com/Widgets/index.html
http://www.x.com/cgi/form/submit.sh?arg=true http://server.hoster.com/cgi/form/submit.sh?arg=true


下面的例子给出了target中包含path prefix的映射例子(与二级域名有关)
map http://www.y.com/marketing/ http://marketing.y.com/
reverse_map http://marketing.y.com/ http://www.y.com/marketing/
map http://www.y.com/sales/ http://sales.y.com/
reverse_map http://sales.y.com/ http://www.y.com/sales/
map http://www.y.com/engineering/ http://engineering.y.com/
reverse_map http://engineering.y.com/ http://www.y.com/engineering/
map http://www.y.com/stuff/ http://info.y.com/
reverse_map http://info.y.com/ http://www.y.com/stuff/
这些例子会导致下面的转换
Client Request                                            Translated Request
http://www.y.com/marketing/projects/manhattan/specs.html http://marketing.y.com/projects/manhattan/specs.html
http://www.y.com/stuff/marketing/projects/boston/specs.html http://info.y.com/marketing/projects/boston/specs.html
http://www.y.com/engineering/marketing/requirements.html http://engineering.y.com/marketing/requirements.html


下面的例子验证了解析规则的优先次序
map http://www.g.com/ http://external.g.com/
reverse_map http://external.g.com/ http://www.g.com/
map http://www.g.com/stuff/ http://stuff.g.com/
reverse_map http://stuff.g.com/ http://www.g.com/stuff/
这将导致下面的转换
Client Request                Translated Request
http://www.g.com/stuff/a.gif http://external.g.com/stuff/a.gif
上面的例子，第二个规则从来不会生效，因为它也适合第一个规则，因为第一个规则在remap.config文件中位置靠前，占得先机。


下面的例子给出了target和replacement中都有path prefix的情况
map http://www.h.com/a/b/ http://server.h.com/customers/x/y
reverse_map http://server.h.com/customers/x/y/ http://www.h.com/a/b/
该规则导致下面的转换
Client Request                    Translated Request
http://www.h.com/a/b/c/d/doc.html http://server.h.com/customers/x/y/c/d/doc.html
http://www.h.com/a/index.html    Translation fails


下面的例子给出了reverse-map规则
map http://www.x.com/ http://server.hoster.com/x/
reverse_map http://server.hoster.com/x/ http://www.x.com/
这导致如下转换
Client Request Translated Request
http://www.x.com/Widgets http://server.hoster.com/x/Widgets
Client Request            Origin Server Header                Translated Request
http://www.x.com/Widgets http://server.hoster.com/x/Widgets/    http://www.x.com/Widgets/
当充当多台服务器的反向代理时，ATS并不能够route那些来自不发送Host头域的旧browser的url，解决办法是在records.config中设置
proxy.config.header.parse.no_host_url_redirect
为ATS要重定向那些没有Host头域请求的url


重定向映射规则Redirect Mapping Rules
redirect http://www.company.com/ http://www.company2.com/
将www.company.com永久重定向到www.company2.com
redirect_temporary http://www.company1.com/ http://www.company2.com/
将www.company1.com暂时重定向到www.company2.com


正则映射支持regex remap
可以在remapping rules中定义正则表达式，但有如下限制条件
a.只有host域可以包含正则表达式，sheme，port及其它域都不行，对path的正则匹配，请试用regex_remap插件
b.捕捉的子模式数限制为9，这意味着$0-$9能被用作子匹配的占位符placeholders, $0表示整个输入字符串
c.表达式中的替换次数限制为10
d.regex_并不等同于reverse_remap，所以当使用regex_remap时，你应该确保reverse path被清楚，通过设置proxy.config.url_remap.pristine_host_hdr


例子
regex_map http://x([0-9]+).z.com/ http://real-x$1.z.com/
regex_redirect http://old.(.*).z.com http://new.$1.z.com


map_with_referer
格式如下
map_with_referer client-URL origin-server-URL redirect-URL regex1 [regex2 ...]
redirect-URL是按照RFC 2616指定的重定向URL，能够获取到重定向url的运行时修改的指定格式指令，
所有描述Referer头内容的正则表达式都必须验证，万一一个实际的请求并没有Referer header或者并不匹配Referer正则表达式， HTTP请求将会被重定向到redirect-URL
为了激活 ‘deep linking protection’，至少得指定一个正则表达式，Referer的正则表达式字符串长度不得超过2048，为了在ATS中能够启用‘deep linking protection’，在records.config中设置 
CONFIG proxy.config.http.referer_filter INT 1
为了启用redirect-URL的运行时格式化，配置
CONFIG proxy.config.http.referer_format_redirect INT 1
随之下面的format symbol能被使用
%r - to substitute original "Referer" header string
%f - to substitute client-URL from 'map_with_referer' record
%t - to substitute origin-server-URL from 'map_with_referer' record
%o - to substitute request URL to origin server, which was created a
     the result of a mapping operation
 
注意：
为了指定请求中Referer头是可选的，可以使用特殊的referer类型"~*".当在map_with_referer mapping中使用"~*"时，带有Referer头的请求将要求验证合法性。
在referer正则表达式前指定"~",表示取反，那些匹配referer头的request将被重定向到redirect-URL。使用它能生成所谓的negative referer list。
在referer正则表达式中指定*，表示通配，所有的referers将被允许。
referer list中*和~的不同组合能生成不同的filtering rules.


map_with_referer例子
map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/new_games .*\.bar\.com www.bar-friends.com
解释：
Referer头必须在request中，只有 ”.*.bar.com” and “www.bar-friends.com”被允许
map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/new_games * ~.*\.evil\.com
解释：
Referer头必须在request中，除了”.*.evil.com”以外，所有的referer都允许
map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/error ~* * ~.*\.evil\.com
解释：
Referer头可选，但是当Referer头存在时，只有来自”.*.evil.com”的请求被重定向到redirect-URL


Plugin Chaining
插件能以特定顺序配置来生效，将前一个插件的执行结果传人后一个插件处理(除非某个插件返回0，插件链才断裂)
示例
map http://url/path http://url/path \
    @plugin=/etc/traffic_server/config/plugins/plugin1.so @pparam=1 @pparam=2 \
    @plugin=/etc/traffic_server/config/plugins/plugin2.so @pparam=3
将参数1和2传入到plugin1.so，将参数3传入到plugin2.so


Acl Filters
能生成Acl Filters去控制特定remap lines的访问，这个语法非常类似于 ip_allow.config，但又略有不同
例子
map http://foo.example.com/neverpost  http://foo.example.com/neverpost @action=deny @method=post
map http://foo.example.com/onlypost  http://foo.example.com/onlypost @action=allow @method=post


map http://foo.example.com/  http://foo.example.com/ @action=deny @src_ip=1.2.3.4
map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=127.0.0.1


map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=10.5.2.1 @in_ip=72.209.23.4


map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=127.0.0.1 @method=post @method=get @method=head
注意到，如果资源受限， Acl filters将会返回403响应码，
@src_ip and @in_ip的区别就是，@src_ip是client ip，in_ip是client建连后的ip address(对端地址)


==未完待续==


remap.config中的疑惑点
reverse_map的真正含义？
将源站响应中的Host域，映射为指定的域


何时使用map，何时使用regex_map？
只有host才能采用正则，所以如果host使用正则时，必须使用regex_map，否则直接使用map


参考文献
[1].https://docs.trafficserver.apache.org/en/latest/reference/configuration/remap.config.en.html