プロキシ自動設定ファイル

この翻訳は不完全です。英語から この記事を翻訳 してください。

 
プロキシ自動設定(Proxy Auto-Configuration, PAC)ファイルはWebブラウザのリクエスト(HTTPやHTTPS,FTP等)が直接宛先に行くか,Webプロキシサーバに転送するか決めるJavaScriptの関数です.
その関数はPACファイルに含まれていて次のように定義します:
function FindProxyForURL(url, host){
    // ...
}        

ret = FindProxyForURL(url, host);

構文

function FindProxyForURL(url, host)

引数

url
アクセスされているURL. https://から始まるURLのパスとクエリ要素は取り除かれます. ChromeではPacHttpsUrlStrippingEnabledfalseに設定することで無効にでき, Firefoxでは network.proxy.autoconfig_url.include_pathtrueにすることで無効にできます.
host
URLから抜き出したホスト名. これは利便性のためのものです. urlの :// と始めの : か / の間にある文字列と同じ文字列です. この引数にはポート番号は含まれません.  必要ならばurlから取り出してください. 

Description

設定を表す文字列を返します. 返す文字列の形式は下の戻り値形式で定義されています.

戻り値形式

  • このJavaScriptの関数は1つの文字列を返す
  • 文字列がnullの場合, プロキシは使用されない
  • 文字列にはセミコロン区切りで以下の設定を複数含むことができる.
DIRECT
接続は直接行われる
PROXY host:port
指定されたプロキシを使用する
SOCKS host:port
指定されたSOCKSサーバを使用する

最近のFirefoxのバージョンでは対応している:

HTTP host:port
指定されたプロキシを使用する
HTTPS host:port
指定されたHTTPSプロキシを使用する
SOCKS4 host:port
SOCKS5 host:port
指定されたSOCKSサーバ(指定されたSOCKバージョン)を使用する

セミコロン区切りで複数の設定をした場合,プロキシとの接続に失敗しない限り一番左の設定が使われます.失敗した場合は次の設定が使われます.

ブラウザは応答しなかったプロキシに対して30分後に再接続を試みます. Additional attempts will continue beginning at one hour, always adding 30 minutes to the elapsed time between attempts.

すべてのプロキシが使用できずDIRECTオプションが設定されていない場合,ブラウザは一時的にプロキシを無視して直接接続するか尋ねます.  After 20 minutes, the browser will ask if proxies should be retried, asking again after an additional 40 minutes. Queries will continue, always adding 20 minutes to the elapsed time between queries.

PROXY w3proxy.netscape.com:8080; PROXY mozilla.netscape.com:8081
1番目のプロキシは w3proxy:8080 です. 1番目のプロキシが使用できない場合は再度使用できるようになるまで mozilla:8081 を使用します.
PROXY w3proxy.netscape.com:8080; PROXY mozilla.netscape.com:8081; DIRECT
上と同じですが両方使用できない場合に自動的に直接接続します. (最初の上の例は,Netscapeはユーザに直接接続するか確認しますが,この例だと確認されません.) 
PROXY w3proxy.netscape.com:8080; SOCKS socks:1080
1番目のプロキシが使用できない場合SOCKSサーバを使います.

自動設定ファイルは .pac 拡張子で保存しなければなりません:

proxy.pac

MIME タイプは以下の様にしてください:

application/x-ns-proxy-autoconfig

次に、MIME形式で.pac拡張子を配置するためにサーバ設定をしてください

ノート:

  • JavaScriptの機能はHTMLにはめ込こまず、単体でファイルを保存すべきです。
  • ドキュメントの最後の例は完全です。ファイルに保存し、使うことで、構文を追加しなくていいのです。(もちろん、JavaScriptはサイトのドメインネーム、またはサブネットに反映されるように編集をしなければなりません。

Predefined functions and environment

These functions can be used in building the PAC file:

Note: pactester (part of the pacparser package) was used to  test the following syntax examples.

  • The PAC file is named proxy.pac
  • Command line: pactester -p ~/pacparser-master/tests/proxy.pac -u http://www.mozilla.org
    • This command passes the host parameter www.mozilla.org and the url parameter http://www.mozilla.org.

isPlainHostName()

Syntax

isPlainHostName(host)

Parameters

host
URLから取り出したホスト名(ポート番号を除いたもの)

Description

ホスト名の中にドメイン名が含まれていない場合(=ドットを含まない)にtrue

Examples

function FindProxyForURL(url, host) {
  if (!isPlainHostName(host))
    return host;
}

//returns "www.mozilla.org"
function FindProxyForURL(url, host) {
  if (isPlainHostName("www"))
    return "isPlainHostName is true";
  return "isPlainHostName is false";
}

//returns "isPlainHostName is true"

dnsDomainIs()

Syntax

dnsDomainIs(host, domain)

Parameters

host
URLから取り出したホスト名
domain
ホストが所属しているか確認したいドメイン名

Description

ホストがドメインに所属する場合にtrue

Examples

function FindProxyForURL(url, host) {
  if (dnsDomainIs("www.mozilla.org", ".mozilla.org"))
    return "dnsDomainIs is true";
  return "dnsDomainIs is false";
}

//returns "dnsDomainIs is true"
function FindProxyForURL(url, host) {
  if (dnsDomainIs("www", ".mozilla.org"))
    return "dnsDomainIs is true";
  return "dnsDomainIs is false";
}

//returns "dnsDomainIs is false"

localHostOrDomainIs()

Syntax

localHostOrDomainIs(host, hostdom)

Parameters

host
The hostname from the URL.
hostdom
Fully qualified hostname to match against.

Description

Is true if the hostname matches exactly the specified hostname, or if there is no domain name part in the hostname, but the unqualified hostname matches.

Examples

function FindProxyForURL(url, host) {
  if (localHostOrDomainIs("www.mozilla.org", "www.mozilla.org"))
    return "localHostOrDomainIs is true (exact match)";
  return "localHostOrDomainIs is false";
}

//returns "localHostOrDomainIs is true (exact match)"
function FindProxyForURL(url, host) {
  if (localHostOrDomainIs("www", "www.mozilla.org"))
    return "localHostOrDomainIs is true (hostname match, domain not specified))";
  return "localHostOrDomainIs is false";
}

//returns "localHostOrDomainIs is true (hostname match, domain not specified))"
function FindProxyForURL(url, host) {
  if (localHostOrDomainIs("www.google.com", "www.mozilla.org"))
    return "localHostOrDomainIs is true";
  return "localHostOrDomainIs is false (domain name mismatch)";
} 

// returns "localHostOrDomainIs is false (domain name mismatch)"
function FindProxyForURL(url, host) {
  if (localHostOrDomainIs("home.mozilla.org", "www.mozilla.org"))
    return "localHostOrDomainIs is true";
  return "localHostOrDomainIs is false (domain name mismatch)"; 
}

// returns "localHostOrDomainIs is false (hostname mismatch)"

isResolvable()

Syntax

isResolvable(host)

Parameters

host
is the hostname from the URL.

Tries to resolve the hostname. Returns true if succeeds.

Examples:

function FindProxyForURL(url, host) {
  if (isResolvable("www.mozilla.org"))
    return "isResolvable is true";
  return "isResolvable is false";
}

// returns "isResolvable is true"

isInNet()

Syntax

isInNet(host, pattern, mask)

Parameters

host
a DNS hostname, or IP address. If a hostname is passed, it will be resolved into an IP address by this function.
pattern
an IP address pattern in the dot-separated format.
mask
mask for the IP address pattern informing which parts of the IP address should be matched against. 0 means ignore, 255 means match.

True if and only if the IP address of the host matches the specified IP address pattern.

Pattern and mask specification is done the same way as for SOCKS configuration.

Examples:

function FindProxyForURL(url, host) {
// put in the address returned by dnsResolve (see next example)
  if (isInNet(host, "63.245.213.24", "255.255.255.255"))
    return "isInNet is true";
  return "isInNet is false";
}

// returns "isInNet is true"

dnsResolve()

dnsResolve(host)

Parameters

host
hostname to resolve.

Resolves the given DNS hostname into an IP address, and returns it in the dot-separated format as a string.

Example

function FindProxyForURL(url, host) {
  return dnsResolve("www.mozilla.org");
} 

//returns the string "104.16.41.2"

convert_addr()

Syntax

convert_addr(ipaddr)

Parameters

ipaddr
Any dotted address such as an IP address or mask.

Concatenates the four dot-separated bytes into one 4-byte word and converts it to decimal.

Example

function FindProxyForURL(url, host) {
  return convert_addr("104.16.41.2");
} 

//returns the decimal number 1745889538

myIpAddress()

Syntax

myIpAddress()

Parameters

(none)

Returns the server IP address of the machine Firefox is running on, as a string in the dot-separated integer format.

myIpAddress() returns the same IP address as the server address returned by nslookup localhost on a Linux machine. It does not return the public IP address.

Example

function FindProxyForURL(url, host) {
  return myIpAddress();
} 

//returns the string "127.0.1.1" if you were running Firefox on that localhost

dnsDomainLevels()

Syntax

dnsDomainLevels(host)

Parameters

host
is the hostname from the URL.

Returns the number (integer) of DNS domain levels (number of dots) in the hostname.

Examples:

function FindProxyForURL(url, host) {
  return dnsDomainLevels("www");
}

//returns 0
function FindProxyForURL(url, host) {
  return dnsDomainLevels("mozilla.org");
}

//returns 1
function FindProxyForURL(url, host) {
  return dnsDomainLevels("www.mozilla.org");
}

//returns 2

shExpMatch()

Syntax

shExpMatch(str, shexp)

Parameters

str
is any string to compare (e.g. the URL, or the hostname).
shexp
is a shell expression to compare against.

Returns true if the string matches the specified shell expression.

Currently, the patterns are shell expressions, not regular expressions.

Examples

function FindProxyForURL(url, host) {
  return shExpMatch("http://home.netscape.com/people/ari/index.html", "*/ari/*");
}

//returns true
function FindProxyForURL(url, host) {
  return shExpMatch("http://home.netscape.com/people/montulli/index.html", "*/ari/*");
}

//returns false

weekdayRange()

Syntax

weekdayRange(wd1, wd2, gmt)

Note: (Before Firefox 49) wd1 must be less than wd2 if you want the function to evaluate these parameters as a range. See the warning below.

Parameters

wd1 and wd2
One of the ordered weekday strings:
"SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"
gmt
Is either the string "GMT" or is left out.

Only the first parameter is mandatory. Either the second, the third, or both may be left out.

If only one parameter is present, the function returns a value of true on the weekday that the parameter represents. If the string "GMT" is specified as a second parameter, times are taken to be in GMT. Otherwise, they are assumed to be in the local timezone.

If both wd1 and wd1 are defined, the condition is true if the current weekday is in between those two ordered weekdays. Bounds are inclusive, but the bounds are ordered. If the "GMT" parameter is specified, times are taken to be in GMT. Otherwise, the local timezone is used.

The order of the days matter; Before Firefox 49, weekdayRange("SUN", "SAT") will always evaluate to true. Now weekdayRange("WED", "SUN") will only evaluate true if the current day is Wednesday or Sunday.

Examples

function FindProxyForURL(url, host) {
  return weekdayRange("MON", "FRI");
}

//returns true Monday through Friday (local timezone)
function FindProxyForURL(url, host) {
  return weekdayRange("MON", "FRI", "GMT");
}

//returns true Monday through Friday (GMT timezone)
function FindProxyForURL(url, host) {
  return weekdayRange("SAT");
}

//returns true true on Saturdays local time
function FindProxyForURL(url, host) {
  return weekdayRange("SAT", "GMT");
}

//returns true on Saturdays GMT time
function FindProxyForURL(url, host) {
  return weekdayRange("FRI", "MON");
}

//returns true Friday and Monday only (note, order does matter!)

dateRange()

Syntax

dateRange(<day1>, <month1>, <year1>, <day2>, <month2>, <year2>, <gmt>)

Note: (Before Firefox 49) day1 must be less than day2, month1 must be less than month2, and year1 must be less than year2 if you want the function to evaluate these parameters as a range. See the warning below.

Parameters

day
Is the ordered day of the month between 1 and 31 (as an integer).
1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31
month
Is one of the ordered month strings below.
"JAN"|"FEB"|"MAR"|"APR"|"MAY"|"JUN"|"JUL"|"AUG"|"SEP"|"OCT"|"NOV"|"DEC"
year
Is the ordered full year integer number. For example, 2016 (not 16).
gmt
Is either the string "GMT", which makes time comparison occur in GMT timezone, or is left out. If left unspecified, times are taken to be in the local timezone.

If only a single value is specified (from each category: day, month, year), the function returns a true value only on days that match that specification. If both values are specified, the result is true between those times, including bounds, but the bounds are ordered.

The order of the days, months, and years matter; Before Firefox 49, dateRange("JAN", "DEC") will always evaluate to true. Now dateRange("DEC", "JAN") will only evaluate true if the current month is December or January.

Examples

function FindProxyForURL(url, host) {
  return dateRange(1);
}

//returns true on the first day of each month, local timezone
function FindProxyForURL(url, host) {
  return dateRange(1, "GMT")
}

//returns true on the first day of each month, GMT timezone
function FindProxyForURL(url, host) {
  return dateRange(1, 15);
}

//returns true on the first half of each month
function FindProxyForURL(url, host) {
  return dateRange(24, "DEC");
}

//returns true on 24th of December each year
function FindProxyForURL(url, host) {
  return dateRange("JAN", "MAR");
}

//returns true on the first quarter of the year
function FindProxyForURL(url, host) {
  return dateRange(1, "JUN", 15, "AUG");
}

//returns true from June 1st until August 15th, each year (including June 1st and August 15th)
function FindProxyForURL(url, host) {
  return dateRange(1, "JUN", 1995, 15, "AUG", 1995);
}

//returns true from June 1st, 1995, until August 15th, same year
function FindProxyForURL(url, host) {
  return dateRange("OCT", 1995, "MAR", 1996);
}

//returns true from October 1995 until March 1996 (including the entire month of October 1995 and March 1996)
function FindProxyForURL(url, host) {
  return dateRange(1995);
}

//returns true during the entire year of 1995
function FindProxyForURL(url, host) {
  return dateRange(1995, 1997);
}

//returns true from beginning of year 1995 until the end of year 1997

timeRange()

Syntax

timeRange(<hour1>, <min1>, <sec1>, <hour2>, <min2>, <sec2>, <gmt>)

Note: (Before Firefox 49) the category hour1, min1, sec1 must be less than the category hour2, min2, sec2 if you want the function to evaluate these parameters as a range. See the warning below.

Parameters

hour
Is the hour from 0 to 23. (0 is midnight, 23 is 11 pm.)
min
Minutes from 0 to 59.
sec
Seconds from 0 to 59.
gmt
Either the string "GMT" for GMT timezone, or not specified, for local timezone.

If only a single value is specified (from each category: hour, minute, second), the function returns a true value only at times that match that specification. If both values are specified, the result is true between those times, including bounds, but the bounds are ordered.

The order of the hour, minute, second matter; Before Firefox 49, timeRange(0, 23) will always evaluate to true. Now timeRange(23, 0) will only evaluate true if the current hour is 23:00 or midnight.

Examples

function FindProxyForURL(url, host) {
  return timerange(12);
}

//returns true from noon to 1pm
function FindProxyForURL(url, host) {
  return timerange(12, 13);
}

//returns true from noon to 1pm
function FindProxyForURL(url, host) {
  return timerange(12, "GMT");
}

//true from noon to 1pm, in GMT timezone
function FindProxyForURL(url, host) {
  return timerange(9, 17);
}

//returns true from 9am to 5pm
function FindProxyForURL(url, host) {
  return timerange(8, 30, 17, 00);
}

//returns true from 8:30am to 5:00pm
function FindProxyForURL(url, host) {
  return timerange(0, 0, 0, 0, 0, 30);
}

//returns true between midnight and 30 seconds past midnight

Example 1

Use proxy for everything except local hosts

Note: Since all of the examples that follow are very specific, they have not been tested.

All hosts which aren't fully qualified, or the ones that are in local domain, will be connected to directly. Everything else will go through w3proxy:8080. If the proxy goes down, connections become direct automatically:

function FindProxyForURL(url, host) {
  if (isPlainHostName(host) || dnsDomainIs(host, ".mozilla.org")) {
    return "DIRECT";
  } else {
    return "PROXY w3proxy.mozilla.org:8080; DIRECT";
  }
}

Note: This is the simplest and most efficient autoconfig file for cases where there's only one proxy.

Example 2

As above, but use proxy for local servers which are outside the firewall

If there are hosts (such as the main Web server) that belong to the local domain but are outside the firewall and are only reachable through the proxy server, those exceptions can be handled using the localHostOrDomainIs() function:

function FindProxyForURL(url, host) {
  if ((isPlainHostName(host) ||
      dnsDomainIs(host, ".mozilla.org")) &&
      !localHostOrDomainIs(host, "www.mozilla.org") &&
      !localHostOrDoaminIs(host, "merchant.mozilla.org")) {
        return "DIRECT";
  } else {
    return "PROXY w3proxy.mozilla.org:8080; DIRECT";
  }
}

The above example will use the proxy for everything except local hosts in the mozilla.org domain, with the further exception that hosts www.mozilla.org and merchant.mozilla.org will go through the proxy.

Note the order of the above exceptions for efficiency: localHostOrDomainIs() functions only get executed for URLs that are in local domain, not for every URL. Be careful to note the parentheses around the or expression before the and expression to achieve the above-mentioned efficient behaviour.

Example 3

Use proxy only if cannot resolve host

This example will work in an environment where the internal DNS server is set up so that it can only resolve internal host names, and the goal is to use a proxy only for hosts that aren't resolvable:

function FindProxyForURL(url, host) {
  if (isResolvable(host))
    return "DIRECT";
  else
    return "PROXY proxy.mydomain.com:8080";
}

The above requires consulting the DNS every time; it can be grouped intelligently with other rules so that DNS is consulted only if other rules do not yield a result:

function FindProxyForURL(url, host) {
  if (isPlainHostName(host) ||
      dnsDomainIs(host, ".mydomain.com") ||
      isResolvable(host)) {
    return "DIRECT";
  } else {
    return "PROXY proxy.mydomain.com:8080";
  }
}

Example 4

Subnet based decisions

In this example all of the hosts in a given subnet are connected-to directly, others are connected through the proxy:

function FindProxyForURL(url, host) {
  if (isInNet(host, "198.95.0.0", "255.255.0.0"))
    return "DIRECT";
  else
    return "PROXY proxy.mydomain.com:8080";
}

Again, use of the DNS server in the above can be minimized by adding redundant rules in the beginning:

function FindProxyForURL(url, host) {
  if (isPlainHostName(host) ||
      dnsDomainIs(host, ".mydomain.com") ||
      isInNet(host, "198.95.0.0", "255.255.0.0")) {
    return "DIRECT";
  } else {
    return "PROXY proxy.mydomain.com:8080";
  }
}

Example 5

Load balancing/routing based on URL patterns

This example is more sophisticated. There are four (4) proxy servers; one of them is a hot stand-by for all of the other ones, so if any of the remaining three goes down the fourth one will take over. Furthermore, the three remaining proxy servers share the load based on URL patterns, which makes their caching more effective (there is only one copy of any document on the three servers -- as opposed to one copy on each of them). The load is distributed like this:

Proxy Purpose
#1 .com domain
#2 .edu domain
#3 all other domains
#4 hot stand-by

All local accesses are desired to be direct. All proxy servers run on the port 8080 (they don't need to). Note how strings can be concatenated with the + operator in JavaScript.

function FindProxyForURL(url, host) {
  if (isPlainHostName(host) || dnsDomainIs(host, ".mydomain.com"))
      return "DIRECT";
  else if (shExpMatch(host, "*.com"))
      return "PROXY proxy1.mydomain.com:8080; " +
             "PROXY proxy4.mydomain.com:8080";
  else if (shExpMatch(host, "*.edu"))
      return "PROXY proxy2.mydomain.com:8080; " +
             "PROXY proxy4.mydomain.com:8080";
  else
      return "PROXY proxy3.mydomain.com:8080; " +
             "PROXY proxy4.mydomain.com:8080";
}

Example 6

Setting a proxy for a specific protocol

Most of the standard JavaScript functionality is available for use in the FindProxyForURL() function. As an example, to set different proxies based on the protocol the substring() function can be used:

function FindProxyForURL(url, host) {
  if (url.substring(0, 5) == "http:") {
    return "PROXY http-proxy.mydomain.com:8080";
  }
  else if (url.substring(0, 4) == "ftp:") {
    return "PROXY ftp-proxy.mydomain.com:8080";
  }
  else if (url.substring(0, 7) == "gopher:") {
    return "PROXY gopher-proxy.mydomain.com:8080";
  }
  else if (url.substring(0, 6) == "https:" ||
           url.substring(0, 6) == "snews:") {
    return "PROXY security-proxy.mydomain.com:8080";
  } else {
    return "DIRECT";
  }
}

Note: The same can be accomplished using the shExpMatch() function described earlier.

For example:

// ...
if (shExpMatch(url, "http:*")) {
  return "PROXY http-proxy.mydomain.com:8080;
}
// ...

The autoconfig file can be output by a CGI script. This is useful, for example, when making the autoconfig file act differently based on the client IP address (the REMOTE_ADDR environment variable in CGI).

Use of isInNet(), isResolvable() and dnsResolve() functions should be carefully considered, as they require the DNS server to be consulted. All the other autoconfig-related functions are mere string-matching functions that don't require the use of a DNS server. If a proxy is used, the proxy will perform its DNS lookup which would double the impact on the DNS server. Most of the time these functions are not necessary to achieve the desired result.

ドキュメントのタグと貢献者

 このページの貢献者: j15338tn, orisano
 最終更新者: j15338tn,