Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_proxy_module.xml @ 535:f8652d663b62
Revised description of "proxy_pass".
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 14 Jun 2012 13:08:13 +0000 |
parents | 5e332fafd228 |
children | ebcb351d9eb3 |
comparison
equal
deleted
inserted
replaced
534:6761e05e5128 | 535:f8652d663b62 |
---|---|
807 <context>location</context> | 807 <context>location</context> |
808 <context>if in location</context> | 808 <context>if in location</context> |
809 <context>limit_except</context> | 809 <context>limit_except</context> |
810 | 810 |
811 <para> | 811 <para> |
812 Sets an address of the proxied server and a URI that maps a location. | 812 Sets the protocol and address of a proxied server, and an optional URI |
813 An address can be specified as a domain name or an address, and a port, | 813 to which a location should be mapped. |
814 for example, | 814 A protocol can be specified as |
815 “<literal>http</literal>” or “<literal>https</literal>”. | |
816 An address can be specified as a domain name or IP address, | |
817 and an optional port: | |
815 <example> | 818 <example> |
816 proxy_pass http://localhost:8000/uri/; | 819 proxy_pass http://localhost:8000/uri/; |
817 </example> | 820 </example> |
818 or as a UNIX-domain socket path: | 821 or as a UNIX-domain socket path specified after the word |
822 “<literal>unix</literal>” and enclosed in colons: | |
819 <example> | 823 <example> |
820 proxy_pass http://unix:/tmp/backend.socket:/uri/; | 824 proxy_pass http://unix:/tmp/backend.socket:/uri/; |
821 </example> | 825 </example> |
822 here a path is specified after the word “<literal>unix</literal>” | |
823 and enclosed in two colons. | |
824 </para> | 826 </para> |
825 | 827 |
826 <para> | 828 <para> |
827 If a domain name resolves to several addresses, all of them will be | 829 If a domain name resolves to several addresses, all of them will be |
828 used in a round-robin fashion. | 830 used in a round-robin fashion. |
829 In addition, an address can be specified as a | 831 In addition, an address can be specified as a |
830 <link doc="ngx_http_upstream_module.xml">server group</link>. | 832 <link doc="ngx_http_upstream_module.xml">server group</link>. |
831 </para> | 833 </para> |
832 | 834 |
833 <para> | 835 <para> |
834 When passing a request to the server, part of a URI matching the location | 836 A request URI is passed to the server as follows: |
835 is replaced by a URI specified in the <literal>proxy_pass</literal> directive. | 837 <list type="bullet" compact="no"> |
836 This rule has two exceptions where a replacement location cannot be | |
837 defined: | |
838 <list type="bullet"> | |
839 | 838 |
840 <listitem> | 839 <listitem> |
841 when a location is specified using a regular expression; | 840 If <literal>proxy_pass</literal> is specified with URI, |
841 when passing a request to the server, part of a | |
842 <link doc="ngx_http_core_module.xml" id="location">normalized</link> | |
843 request URI matching the location is replaced by a URI | |
844 specified in the directive: | |
845 <example> | |
846 location /name/ { | |
847 proxy_pass http://127.0.0.1/remote/; | |
848 } | |
849 </example> | |
842 </listitem> | 850 </listitem> |
843 | 851 |
844 <listitem> | 852 <listitem> |
845 if a URI is changed using the | 853 If <literal>proxy_pass</literal> is specified without URI, |
846 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive | 854 a request URI is passed to the server in the same form |
847 inside a proxied location, and this same configuration will be | 855 as sent by a client when processing an original request, |
848 used to process a request (<literal>break</literal>): | 856 or the full normalized request URI is passed |
857 when processing the changed URI: | |
858 <example> | |
859 location /some/path/ { | |
860 proxy_pass http://127.0.0.1; | |
861 } | |
862 </example> | |
863 <note> | |
864 Before version 1.1.12, | |
865 if <literal>proxy_pass</literal> is specified without a URI, | |
866 an original request URI might be passed | |
867 instead of the changed URI in some cases. | |
868 </note> | |
869 </listitem> | |
870 </list> | |
871 </para> | |
872 | |
873 <para> | |
874 In some cases, part of a request URI to be replaced cannot be determined: | |
875 <list type="bullet" compact="no"> | |
876 | |
877 <listitem> | |
878 When location is specified using a regular expression. | |
879 <para> | |
880 In this case, the directive should be specified without URI. | |
881 </para> | |
882 </listitem> | |
883 | |
884 <listitem> | |
885 When URI is changed inside a proxied location using the | |
886 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive, | |
887 and this same configuration will be used to process a request | |
888 (<literal>break</literal>): | |
849 <example> | 889 <example> |
850 location /name/ { | 890 location /name/ { |
851 rewrite /name/([^/]+) /users?name=$1 break; | 891 rewrite /name/([^/]+) /users?name=$1 break; |
852 proxy_pass http://127.0.0.1; | 892 proxy_pass http://127.0.0.1; |
853 } | 893 } |
854 </example> | 894 </example> |
855 In these cases a URI is passed without mapping. | 895 <para> |
896 In this case, a URI specified in the directive is ignored and | |
897 the full changed request URI is passed to the server. | |
898 </para> | |
856 </listitem> | 899 </listitem> |
857 | |
858 </list> | 900 </list> |
859 </para> | 901 </para> |
860 | 902 |
861 <para> | 903 <para> |
862 It can also be specified that a request URI should be passed unchanged, | 904 A server name, its port and passed URI can also be specified using variables: |
863 in the same form it was sent by the client, not the processed form. | |
864 During a processing | |
865 <list type="bullet"> | |
866 | |
867 <listitem> | |
868 two or more adjacent slashes are replaced by one: “//” — “/”; | |
869 </listitem> | |
870 | |
871 <listitem> | |
872 links to the current directory get removed: “/./” — “/”; | |
873 </listitem> | |
874 | |
875 <listitem> | |
876 links to the parent directory get removed: “/dir/../” — “/”. | |
877 </listitem> | |
878 | |
879 </list> | |
880 </para> | |
881 | |
882 <para> | |
883 If a URI should be passed unchanged then the server URL should be specified | |
884 without a URI in the <literal>proxy_pass</literal> directive: | |
885 <example> | |
886 location /some/path/ { | |
887 proxy_pass http://127.0.0.1; | |
888 } | |
889 </example> | |
890 </para> | |
891 | |
892 <para> | |
893 Server name, its port, and passed URI can be specified using variables: | |
894 <example> | 905 <example> |
895 proxy_pass http://$host$uri; | 906 proxy_pass http://$host$uri; |
896 </example> | 907 </example> |
897 or like this: | 908 or even like this: |
898 <example> | 909 <example> |
899 proxy_pass $request; | 910 proxy_pass $request; |
900 </example> | 911 </example> |
901 </para> | 912 </para> |
902 | 913 |