4.13. The io Section

The <io/> section of the jabber.xml configuration file, shown in Example 4-20 and represented in diagram form in Figure 4-17, is where a number of settings relating to socket communication with the Jabber server are set.

Example 4-20. jabber.xml configuration for the io section

<io>

  <karma>
    <heartbeat>2</heartbeat>
    <init>64</init>
    <max>64</max>
    <inc>6</inc>
    <dec>1</dec>
    <penalty>-3</penalty>
    <restore>64</restore>
  </karma>

  <rate points="5" time="25"/>

</io>

Figure 4-17. Diagram view of io section

Although a distinct section, io does not describe a component with custom configuration or a connection method; the contents are merely settings. Let's examine each of these settings here.

4.13.1. The <rate/> Tag

The <rate/> tag affords us a sort of connection throttle by allowing us to monitor the rate at which incoming connections are made and to put a hold on further connections if the rate is reached.

The rate is calculated to be a number of connection attempts—from a single IP address—within a certain amount of time. We can see these two components of the rate formula as attributes of the <rate/> tag itself:

<rate points="5" time="25"/>

This means acceptance of incoming connections from an individual IP address will be stopped if more than five connection attempts (points) are made in the space of 25 seconds (time).

The "rating" (the throttling of connection attempts) will be restored at the end of the period defined (25 seconds in this case).

The effect of a <rate/> tag in this io section is serverwide; all socket connections (for example, those of c2s and s2s) can be rate-limited. If there is no explicit <rate/> specification in a particular service that listens on a socket for connections, then the specification in this io section is used. If no <rate/> tag is specified in this io section, then the server defaults are used—these are actually the same as what's explicitly specified here.

4.13.2. The <karma/> Tag

Like the <rate/> tag, <karma/> is used to control connectivity. Whereas rating helps control the number of connections, karma allows us to control the data flow rate per connection once a connection has been made.

The concept of karma is straightforward; each socket has a karma value associated with it. We can understand it better if we think of it as each entity (connecting through a socket) having a karma value. The higher the value—the more karma—an entity has, the more data it is allowed to send through the socket. So as rating is a throttle for connections, so karma is a throttle for data throughput.

There are certain settings that allow us to fine-tune our throughput throttle. Table 4-6 lists these settings, along with the values explicitly set in each of the c2s and s2s component sections in our jabber.xml file. Notice how the settings for the Server (to Server) Connections component are considerably higher than those for the Client (to Server) Connections—this is based on the assumption that server-to-server traffic will be greater than client-to-server on a socket-by-socket basis.

The relationship between an entity's karma and how much data it is allowed to write to the socket is linear; in fact, the amount is:

(karma value * 100)

and this every 2 seconds. The multiplier (100) and the karma period (2) are hardcoded into the server; a recompilation would be required to change these values.

Over time, an entity's karma value will increase, up to a maximum value (we need a ceiling on how much we're going to allow an entity to send!) every karma period (2 seconds).

The same karma formula is used to penalize an entity for sending too much data. If more than (karma * 100) bytes are sent within a certain period, the entity's karma value is decreased. Once the value reaches 0, it is plunged to a negative number, meaning that the entity must take a breather until the value grows back to 0 (over time, it will). At this point, the value will be restored to a value that gives the entity a chance to start sending data again.

4.13.3. The <ssl/> Tag

If you have compiled your Jabber server with SSL (see Chapter 3) and want to use SSL-encrypted connections, you will have to have specified the <ssl/> tags in the configuration of the c2s component instance. Furthermore, you must specify the location of your SSL certificate and key file. There is an <ssl/> tag in this io section for this purpose.

You can have separate files for each IP address specified in the c2s component instance configuration's <ssl/> tag. Example 4-21 shows the specification of two .pem files—one for each of two IP addresses.

Example 4-21. Specifying SSL certificate and key files per IP address

<ssl>
  <key ip="192.168.0.4">/usr/local/ssl/certs/ks1.pem</key>
  <key ip="192.168.9.1">/usr/local/ssl/certs/ks2.pem</key>
</ssl>

4.13.4. The <allow/> and <deny/> Tags

You can control at the IP address and network level who can connect to your Jabber server with the <allow/> and <deny/> tags.

The default (when no tags are specified) is to allow connections from everywhere. If you use <allow/> tags, then connections will be allowed only from the addresses or networks specified. If you use <deny/> tags, then connections will be denied from those addresses or networks specified. If you have both <allow/> and <deny/> tags, the intersection of addresses between the two tag sets will be denied. In other words, <deny/> overrides <allow/>.

The tags wrap individual IP addresses, which are specified using the <ip/> tag, or network addresses, which are specified using the <ip/> tag in combination with the <mask/> netmask tag. Example 4-22 shows connections to a Jabber server being limited to hosts from two internal networks with the exception of one particular IP address, and a specific host on the Internet.

Example 4-22. Using <allow/> and <deny/> to control connections

<allow>
  <ip>192.168.10.0</ip>
  <mask>255.255.255.0</mask>
</allow>

<allow>
  <ip>192.168.11.0</ip>
  <mask>255.255.255.0</mask>
</allow>

<allow>
  <ip>195.82.105.244</ip>
</allow>

<deny>
  <ip>192.168.11.131</ip>
</deny>