3. Capabilities and limitations
- All of the modules are global. i.e. There is still only one
-"modules" section.
-
- The only sub-sections that can appear in a virtual server are:
+ The only sub-sections that can appear in a virtual server sectopm
+are:
listen
client
accounting
session
- The authorize, etc. sections have their normal meaning, and can
-contain anything that an authorize section could contain in 1.x.
+ All other configuration parameters (modules, etc.) are global.
+
+ Inside of a virtual server, the authorize, etc. sections have their
+normal meaning, and can contain anything that an authorize section
+could contain in 1.x.
When a "listen" section is inside of a virtual server definition, it
means that all requests sent to that IP/port will be processed through
-the virtual server.
+the virtual server. There cannot be two "listen" sections with the
+same IP address and port number.
When a "client" section is inside of a virtual server definition, it
means that that client is known only to the "listen" sections that are
also inside of that virtual server. Not only is this client
-definition available only to this virtual server, but the client
-configuration is also available to this virtual server.
-
- i.e. Each virtual server can list a client IP address 127.0.0.1, and
-each virtual server can have a different shared secret for that client.
+definition available only to this virtual server, but the details of
+the client configuration is also available only to this virtual
+server.
- If you do specify one or more "client" sections in a virtual server,
-it means that only those clients are available to that server. Any
-other clients are treated as unknown by that virtual server.
+ i.e. Two virtual servers can listen on different IP address and
+ports, but both can have a client with IP address 127.0.0.1. The
+shared secret for that client can be different for each virtual
+server.
-4. More complex capabilities
+4. More complex "listen" capabilities
The "listen" sections have a few additional configuration items that
were not in 1.x, and were not mentioned above. These configuration
through the named virtual server.
This directive can be used only for "listen" sections
- that are standing on their own. i.e. It CANNOT be
- used if the "listen" section is inside of a virtual
- server.
+ that are global. i.e. It CANNOT be used if the
+ "listen" section is inside of a virtual server.
clients = <name>
then that "listen" section will ONLY use the second
client. It will NOT use both clients.
+
+5. More complex "client" capabilities
+
+ The "client" sections have a few additional configuration items that
+were not in 1.x, and were not mentioned above. These configuration
+items enable almost any mapping of IP / port to clients to virtual
+servers.
+
+ The configuration items are:
+
+ server = <name>
+
+ If set, all requests from this client are processed
+ through the named virtual server.
+
+ This directive can be used only for "client" sections
+ that are global. i.e. It CANNOT be used if the
+ "client" section is inside of a virtual server.
+
+ If the "listen" section has a "server" entry, and a matching
+client is found ALSO with a "server" entry, then the clients server is
+used for that request.
+
+
+6. Worked examples
+
+
+ Listening on one socket, and mapping requests from two clients to
+two different servers.
+
+ listen {
+ ...
+ }
+ client one {
+ ...
+ server = server_one
+ }
+ client two {
+ ...
+ server = server_two
+ }
+ server server_one {
+ authorize {
+ ...
+ }
+ ...
+ }
+ server server_two {
+ authorize {
+ ...
+ }
+ ...
+ }
+
+ This could also be done as:
+
+
+ listen {
+ ...
+ server = server_one
+ }
+ client one {
+ ...
+ }
+ client two {
+ ...
+ server = server_two
+ }
+ server server_one {
+ authorize {
+ ...
+ }
+ ...
+ }
+ server server_two {
+ authorize {
+ ...
+ }
+ ...
+ }
+
+ In this case, the default server for the socket is "server_one", so
+there is no need to set that in the client "one" configuration. The
+"server_two" configuration for client "two" over-rides the default
+setting for the socket.
+
+ Note that the following configuration will NOT work:
+
+ listen {
+ ...
+ server = server_one
+ }
+ client one {
+ ...
+ }
+ server server_one {
+ authorize {
+ ...
+ }
+ ...
+ }
+ server server_two {
+ client two {
+ ...
+ }
+ authorize {
+ ...
+ }
+ ...
+ }
+
+ In this example, client "two" is hidden inside of the virtual
+server, where the "listen" section cannot find it.
+
+
+7. Outlined examples
+
+ This section outlines a number of examples, with alternatives.
+
+ One server, multiple sockets
+ - multiple "listen" sections in a "server" section
+
+ one server per client
+ - define multiple servers
+ - have a global "listen" section
+ - have multiple global "clients", each with "server = X"
+
+ two servers, each with their own sockets
+ - define multiple servers
+ - put "client" sections into each "server"
+ - put a "listen" section into each "server"
+
+ Each server can list the same client IP, and the secret
+ can be different
+
+ two sockets, sharing a list of clients, but pointing to different servers
+ - define global "listen" sections
+ - in each, set "server = X"
+ - in each, set "clients = Y"
+ - define "clients Y" section, containing multiple clients.
+
+ This also means that you can have a third socket, which
+ doesn't share any of these clients.
+
+
+8. How to decide what to do
+
+
+ If you want *completely* separate policies for a socket or a client,
+then create a separate virtual server. Then, map the request to that
+server by setting configuration entries in a "listen" section or in a
+"client" section.
+
+ Start off with the common cases first. If most of the clients
+and/or sockets get a particular policy, make that policy the default.
+Configure it without paying attention to the sockets or clients you
+want to add later, and without adding a second virtual server. Once
+it works, then add the second virtual server.
+
+ If you want to re-use the previously defined sockets with the second
+virtual server, then you will need one or more global "client"
+sections. Those clients will contain a "server = ..." entry that will
+direct requests from those clients to the appropriate virtual server.