4.6. Component Instance: c2s

The c2s component, described by the configuration XML shown in Example 4-12 and shown in diagram form in Figure 4-9, provides the Client (to Server) Connections service—it manages Jabber client connections to the Jabber server.

Figure 4-9. Diagram view of c2s component instance

Example 4-12. jabber.xml configuration for the c2s component instance

<service id="c2s">

  <load>
    <pthsock_client>./pthsock/pthsock_client.so</pthsock_client>
  </load>

  <pthcsock xmlns='jabber:config:pth-csock'>
    <authtime/>
    <karma>
      <init>10</init>
      <max>10</max>
      <inc>1</inc>
      <dec>1</dec>
      <penalty>-6</penalty>
      <restore>10</restore>
    </karma>
    <ip port="5222"/>
  </pthcsock>

</service>

4.6.1. Component Type and Identification

The opening tag:

<service id="c2s">

identifies this component instance to the backbone as a service type component and gives it the name c2s.

4.6.2. Host Filter

The c2s component has no explicit <host/> tag; the identification of the service with the id attribute is enough, and the value of the host filter will be taken as that identification. As long as the specified ID is unique within the context of the whole configuration, the component will be able to function correctly. It is normally set to c2s by convention.

4.6.3. Custom Configuration

The custom configuration for our c2s component contains three main tags:

<authtime/>

The first tag, <authtime/>, allows us to specify a time limit within which the connecting client has to have completed the authentication procedure. This includes sending the initial document stream identifier with the jabber:client namespace. Setting this to, say, 10 seconds:

<authtime>10</authtime>

will allow the client up to 10 seconds to authenticate, after which c2s will drop the connection. Setting the time limit to 0 seconds, which can be accomplished with an empty tag:

<authtime/>

effectively gives the client an unlimited amount of time within which to authenticate.

<karma/>

The next tag we find in the c2s component instance configuration is <karma/>. This is a way of controlling bandwidth usage through the connections and will be explained in Section 4.13 later in this chapter.

<ip/>

Then we come to the <ip/> configuration tag:

<ip port="5222"/>

The standard port for client connections is 5222. This is where it is specified—in the port attribute. The <ip/> tag itself can contain an IP address or hostname. If you specify something like this:

<ip port="5222">192.168.0.4</ip>

then only socket connections will be made to that specific combination of port and IP address. Not specifying an IP address means that the c2s service will bind to the port on all (INADDR_ANY) IP addresses on the host.

You can specify more than one combination of port and IP address using multiple <ip/> tags:

<ip port="5222">
<ip port="5225">127.0.0.1</ip>

which here means client socket connections will be listened for on port 5222 on any IP address and port 5225 on the localhost address.

Three other configuration tags—<rate/>, <alias/>, and <ssl/>—are not used here but are worth identifying now:

<rate/>

<rate/>, like <karma/>, is used to control connectivity and will be explained along with that tag in Section 4.13 later.

<alias/>

<alias/> is a way of providing alias names for your Jabber server. When a Jabber client makes a connection, the opening gambit is the root of the XML document that is to be streamed over the connection:

<stream:stream to="furrybeast" xmlns="jabber:client"
               xmlns:stream="http://etherx.jabber.org/streams">

The use of furrybeast may be a DNS alias for yak and is specified by the client here in the to attribute of the document's root tag (<stream/>).

With the <alias/> tag, we can "fix" the incoming host specification by replacing it with what we as the server want it to be. If this document root tag were to be sent to our Jabber server configured as yak and we had an <alias/> tag thus:

<alias to="yak">furrybeast</alias>

then the incoming hostname specification furrybeast would be recognized and translated to yak in the response:

<stream:stream xmlns:stream='http://etherx.jabber.org/streams'
               id='3AE71597' xmlns='jabber:client' from='yak'>

Rather than specify a hostname to translate, a default alias name can be specified like this:

<alias to="yak"/>

meaning that any connections to the c2s component would have their Jabber hostname specification translated to yak if necessary. This is an indication to the client that the hostname yak should be used in any reference to that Jabber server.

<ssl/>

<ssl/> is the equivalent of the <ip/> tag and works in exactly the same way, with two exceptions:

• An IP address must be specified, which means that something like <ssl port="5223"/> is not allowed.

• The connections are encrypted using SSL, which means that the Jabber server must have been configured to use SSL (see Chapter 3 and Section 4.13 later in this chapter for details).

4.6.4. Component Connection Method

The component connection method is library load:

<load>
  <pthsock_client>./pthsock/pthsock_client.so</pthsock_client>
</load>

The shared library ./pthsock/pthsock_client.so is loaded and the pthsock_client() function is called to initialize the component.