Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_proxy_module.xml @ 535:f8652d663b62

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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