ICQ Transport 0.9.1 documentation

To build, make sure the icq-transport directory is in your Jabber 1.4 directory
and type 'make'.

Configuration
-------------

Below is an example configuration of ICQ-transport. This config is setup to run
in the same process as JSM.  Add this to your jabber.xml file and change all
occurrences icq.mydomain.

  <service id="icq.mydomain">

    <icqtrans xmlns="jabber:config:icqtrans">

      <!-- This tag contains the message displayed to users at registration time. -->
      <instructions>Please enter your ICQ number (in the "username" field), nickname, and password.  Leave the "username" field blank to create a new ICQ number.</instructions>

      <!-- contains the message displayed when users search with ICQ Transport. -->
      <search>Search for ICQ users</search>

      <!-- Contains the vCard of this transport. -->
      <vCard>
        <FN>ICQ Transport</FN>
        <DESC>This is ICQ Transport</DESC>
        <URL>http://foo.bar/</URL>
      </vCard>

      <!-- <chat/> ICQ-t sending normal/single messages by default -->

      <!-- This should be a prime number close to the amount of concurrent users you expect to have. -->
      <prime>501</prime>

      <!-- enables full TCP support -->
      <tcp><ports/></tcp>

      <!--   Use the <ports/> to control the port range ICQ will use to listen for
	     incomming TCP connections.  If the ports section is not present,
	     ICQ-t will not listen on any port and make outgoing TCP connections only.
	     Remove the TCP section to disable TCP completely -->
      <tcp>

        <ports>
          <min>2000</min>
          <max>3000</max>
        </ports>
      </tcp>
      -->

      <!-- dnsrv section, see below for explanation.
           This section isn't needed if your using your own ICQ server, Groupware or whatever -->
      <dnsrv>
        <host>icq.mirabilis.com</host>  <!-- ICQ server to resolve -->
        <id>icq.dnsrv</id>              <!-- service id of our dnsrv component -->
        <delay>300</delay>              <!-- 5 minute delay between updates -->
      </dnsrv>

      <!-- This specifies what ICQ server and/or port you want to use.  This isn't needed if you're using dnsrv.

      <server>
        <ip>205.188.153.104</ip>
        <port>4000</port>
      </server>
       -->

      <!-- only supports <who/> from jabber:iq:admin
      <admin>
        <read>sheath@jabber.org</read>
        <read>admin@jabber.org</read>
      </admin>
      -->

    </icqtrans>

    <load>
      <icqtrans>./icq-transport/icqtrans.so</icqtrans>
    </load>

  </service>

Normally, ICQ-transport needs to periodically resolve icq.mirabilis.com.  It can't do this in process
so it uses it's own dnsrv to do the work for it.  So add this to your config as well, to load
and configure a dnsrv instance:

  <service id="icq.dnsrv">
    <load>
      <dnsrv>./dnsrv/dnsrv.so</dnsrv>
    </load>
    <dnsrv xmlns="jabber:config:dnsrv">
      <resend>icq.mydomain</resend>      <!-- Change this to the service id for ICQ-transport -->
      <cachetimeout>300</cachetimeout>   <!-- the default is 1 hour, which is too long for our purpose -->
    </dnsrv>
  </service>

You will also need to modify your JSM configuration to make the transport
visible when browsing.  Do so by adding a new service tag to your browse
section:

  <browse>

    <!-- Don't forget to change the jid attribute -->

    <service type="icq" jid="icq.mydomain" name="ICQ Transport">
      <ns>jabber:iq:gateway</ns>
      <ns>jabber:iq:register</ns>
      <ns>jabber:iq:search</ns>
    </service>

    ...

  </browse>

Firewalls and TCP
-----------------

ICQ transport must make an outgoing UDP connection to the ICQ server on port
4000, make sure it can do so.

ICQ clients normally uses peer 2 peer TCP connections to communicate between
clients.  They listen on a TCP port and accept any incoming connections.
Outgoing TCP connections to other ICQ clients are also frequently made.

It is possible to configure ICQ transport not to listen on any TCP port and only
make outgoing connections.  Unfortunately, it is not possible to predict the
port numbers and IP addresses which ICQ transport will have to connect.

So if you're going to run ICQ transport behind a firewall, you will probably
have to disable TCP altogether.  Messages will be sent through the server and no
functionality will be lost by doing so.

To disable listening TCP, remove the <ports/> section from the <tcp/> section.
To disable TCP altogether, remove the <tcp/> section entirely.

Disabling TCP has the added benefit of hiding the IP address of ICQ transport
from other ICQ clients.  It will also significantly cut down on the number of
sockets used.  So you may want to disable TCP anyway, even if you your not
behind a firewall.

Separate Process
----------------

ICQ Transport can also be run in its own jabberd process.  To do so, create a
new file called icqtrans.xml which contains the following.

<jabber>

  <!-- This connects the ICQ-transport process to the master process -->
  <service id="icqlinker">
    <uplink/>
    <connect>
      <ip>127.0.0.1</ip>
      <port>1234</port>
      <secret>test</secret>
    </connect>
  </service>

  <service id="icq.mydomain">

    <icqtrans xmlns="jabber:config:icqtrans">

      <!-- See above example of what to put in here -->

    </icqtrans>

    <load>
      <icqtrans>./icq-transport/icqtrans.so</icqtrans>
    </load>

  </service>

  <dnsrv id="icq.dnsrv">

    <!-- See above example -->

    <load>
      <dnsrv>./dnsrv/dnsrv.so</dnsrv>
    </load>

  </dnsrv>

</jabber>

In your master jabber.xml file add the following section:

  <service id="icqlinker">
    <host>icq.mydomain</host>
    <accept>
      <ip>127.0.0.1</ip>
      <port>1234</port>
      <secret>test</secret>
    </accept>
  </service>
