diff --git a/topics/clustering/load-balancer.adoc b/topics/clustering/load-balancer.adoc index 783b4c9760..9421d6547e 100755 --- a/topics/clustering/load-balancer.adoc +++ b/topics/clustering/load-balancer.adoc @@ -1,10 +1,113 @@ -=== Setting Up a Load Balancer +=== Setting Up a Load Balancer or Proxy -This section only covers configuring the built in load balancer that is discussed in the +This section discusses a number of things you need to configure before you can put a reverse proxy or load balancer +in front of your clustered {{book.project.name}} deployment. It also covers configuring the built in load balancer that +was <>. + + +==== Identifying Client IP Addresses + +A few features in {{book.project.name}} rely on the fact that the remote +address of the HTTP client connecting to the authentication server is the real IP address of the client machine. This can +be problematic when you have a reverse proxy or loadbalancer in front of your {{book.project.name}} authentication server. +The usual setup is that you have a frontend proxy sitting on a public network that load balances and forwards requests +to backend {{book.project.name}} server instances that sin on a private network. There is some extra configuration you have to do in this scenario +so that the actual client IP address is forwarded to and processed by the {{book.project.name}} server instances. Specifically: + +* Configure your reverse proxy (loadbalancer) to properly set `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers. +* Configure the authentication server to read the client's IP address from `X-Forwarded-For header`. + +Configuring your proxy to generate the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers is beyond the scope of this +guide. Take extra precautions to ensure that the +`X-Forwared-For` header is set by your proxy. If your proxy isn't configured correctly, then _rogue_ clients can set this header themselves and trick {{book.project.name}} +into thinking the client is connecting from a different IP address than it actually is. This becomes really important if you are doing +any black or white listing of IP addresses. + +Beyond the proxy itself, there are a few things you need to configure on the {{book.project.name}} side of things. +If your proxy is forwarding requests via the HTTP protocol, then you need to configure {{book.project.name}} to pull the client's +IP address from the `X-Forwarded-For` header rather than from the network packet. +To do this, open up the profile configuration file (_standalone.xml, _standalone-ha.xml_, or _domain.xml_ depending on your +<>) and look for the `"urn:jboss:domain:undertow:3.0` XML block. + +.`X-Forwarded-For` HTTP Config +[source,xml] +---- + + + + + + ... + + ... + +---- + +Add the `proxy-address-forwarding` attribute to the `http-listener` element. Set the value to `true`. + +If your proxy is using the AJP protocol instead of HTTP to forward requests (i.e. Apache HTTPD + mod-cluster), then you have +to configure things a little differently. Instead of modifying the `http-listener`, you need to add a filter to +pull this information from the AJP packets. + + +.`X-Forwarded-For` AJP Config +[source,xml] +---- +< + + + + + + ... + + + + ... + + ... + + + +---- + +==== Enable HTTPS/SSL with a Reverse Proxy + +Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port HTTPS traffic is redirected to. +[source,xml] +---- + + ... + + ... + +---- + +Add the `redirect-socket` attribute to the `http-listener` element. The value should be `proxy-https` which points to a +socket binding you also need to define. + +Then add a new `socket-binding` element to the `socket-binding-group` element: + +[source] +---- + + + ... + + ... + +---- + +==== Using the Built-In Load Balancer + +This section covers configuring the built in load balancer that is discussed in the <>. -The link:{{book.appserver.loadbalancer.link}}[the load balancer] chapter of the {{book.appserver.loadbalancer.name}} -has information on using some other software based load balancers that may help you. The <> is only designed to run on one machine. To bring up a slave on another host, you'll need to @@ -14,7 +117,9 @@ on one machine. To bring up a slave on another host, you'll need to the _standalone/_ directory. . Edit the _host-slave.xml_ file to change the bind addresses used or override them on the command line -==== Register a New Host With Load Balancer + + +===== Register a New Host With Load Balancer Let's look first at registering the new host slave with the load balancer configuration in _domain.xml_. Open this file and go to the undertow configuration in the `load-balancer` profile. Add a new `host` definition called @@ -60,7 +165,7 @@ binding needs to point to the host and port of the new host. ---- -==== Master Bind Addresses +===== Master Bind Addresses Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host. Either edit the _domain.xml_ file as discussed in the <> chapter @@ -71,7 +176,7 @@ or specify these bind addresses on the command line as follows: $ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2 ---- -==== Host Slave Bind Addresses +===== Host Slave Bind Addresses Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`). Either edit the _host-slave.xml_ file or specify them on the command line as follows: @@ -88,5 +193,11 @@ The values of `jboss.bind.address` and `jboss.bind.addres.management` pertain to The value of `jboss.domain.master.address` need to be the IP address of the domain controller which is the management address of the master host. +==== Configuring Other Load Balancers + +The link:{{book.appserver.loadbalancer.link}}[the load balancer] chapter of the {{book.appserver.loadbalancer.name}} +has information on using some other software based load balancers that may help you. + + diff --git a/topics/network/bind-address.adoc b/topics/network/bind-address.adoc index 884d1a2e60..9619ed0c77 100755 --- a/topics/network/bind-address.adoc +++ b/topics/network/bind-address.adoc @@ -20,7 +20,7 @@ The `-b` switch sets the IP bind address for any public interfaces. Alternatively, if you don't want to set the bind address at the command line, you can edit the profile configuration of your deployment. Open up the profile configuration file (_standalone.xml or _domain.xml_ depending on your -<> and look for the `interfaces` XML block. +<>) and look for the `interfaces` XML block. [source,xml] ---- diff --git a/topics/network/https.adoc b/topics/network/https.adoc index 8557e75fd9..0f70786fd6 100755 --- a/topics/network/https.adoc +++ b/topics/network/https.adoc @@ -22,45 +22,6 @@ all:: The SSL mode for each realm can be configured in the {{book.project.name}} admin console. -==== Enable HTTPS/SSL with a Reverse Proxy - -It is general best practice that {{book.project.name}} will be run in a cluster with a reverse proxy or hardware load balancer -setting in front of {{book.project.name}} server instances. - -To enable SSL/HTTPS in this deployment scenario, it is important that you make sure your reverse proxy sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to {{book.project.name}}. -To make sure that {{book.project.name}} honors these headers, you need to enable the `proxy-address-forwarding` setting of the {{book.project.name}} http connector in {{book.project.name}} configuration. -Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to. - -. Open _standalone.xml_, _standalone-ha.xml_, or _domain.xml_ file (depends on your <>). - -. Add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element: - -[source] ----- - - ... - - ... - ----- - -Then add a new `socket-binding` element to the `socket-binding-group` element: - -[source] ----- - - - ... - - ... - ----- - -Also remember that when running in <> what `socket-binding-group` -you modify depends on how you have your server groups configured. - ==== Enabling SSL/HTTPS for the {{book.project.name}} Server If you are not using a reverse proxy or load balancer to handle HTTPS traffic for you, you'll need to enable HTTPS