This needs to be formatted correctly for Google's Wiki Syntax.
=Introduction=
Welcome to the online documentation for PyAIMt! This will always be the most up to date documentation available for the transport and, at some point, may replace that which is distributed with the transport altogether. Multiple authors help keep this documentation up to date and I expect it to continue to improve as time goes on. If you have external documentation related to the transport, please let us know and we will add in a link! Also do not be afraid to let us know what could be improved!
In my neverending quest to make PyAIMt feature rich, I'm attempting to put
up a list of currently supported features, and planned features. Drop me
a note if there is something you would like that is not listed here:
|| Feature || Description || Status ||
|| Messaging || Ability to message users on AIM, and receive messages. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Presence || Ability to see others online, and others to see you. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Group Chat || Ability to join and talk in chat rooms. || <FONT COLOR='#ffcc00'>Partial[[#groupchat|<FONT STYLE='font-size: 60%'><SUP>6</SUP></FONT>]]</FONT> ||
|| VCard Support || Ability to request a VCard of an AIM user. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| HTML Messages || Color and fonts in messages. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Typing Notifications || Notifications when typing starts on either end. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| New E-mail Notifications || Receive notifications when one of your AIM e-mail addresses (netscape.net, etc.) has unread messages. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Change AIM password || Change the password you use to log on to your AIM account || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Change registered e-mail address || Change the e-mail address you've registered with AIM || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Format AIM screenname || Change the capitals of your screenname or add spaces to it || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Confirm AIM account || Confirm the screenname you've entered is actually an AIM account || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| Crosschat support || Exchange messages, presence, etc. with ICQ users. || <FONT COLOR='#00aa00'>Complete</FONT> ||
|| File Transfer || Ability to send files between AIM and Jabber || <FONT COLOR='#aa0000'>Incomplete</FONT>[[#filetransfer|<FONT STYLE='font-size: 60%'><SUP>1</SUP></FONT>]] ||
|| Image messaging || Ability to send/recieve images embedded in messages || <FONT COLOR='#aa0000'>Incomplete</FONT>[[#imagemessaging|<FONT STYLE='font-size: 60%'><SUP>2</SUP></FONT>]] ||
|| Message Encryption || Ability to encrypt messages in Trillian's style. || <FONT COLOR='#aa0000'>Incomplete</FONT> ||
|| Linked screennames
|| Ability to use screennames that are linked to your main screenname
<FONT STYLE='font-size: 80%'><SPAN ID=filetransfer>1</SPAN> - [http://www.jabber.org/jeps/jep-0096.html JEP 96] on file transfers is not finalized yet.</FONT>
<br />
<FONT STYLE='font-size: 80%'><SPAN ID=imagemessaging>2</SPAN> - There might not be a suitable JEP on the Jabber side for this. Maybe base64ed images in XHTML?</FONT>
<br />
<FONT STYLE='font-size: 80%'><SPAN ID=linkedscreennames>3</SPAN> - This might also be tricky to support on the Jabber side.</FONT>
<br />
<FONT STYLE='font-size: 80%'><SPAN ID=signup>4</SPAN> - You can sign up for a screenname [http://channels.netscape.com/wrap/linker.jsp?floc=main_1_5&ref=http://my.screenname.aol.com/_cqr/login/login.psp?seamless=n&createSn=1&sitedomain=www.aim.com&siteState=http%3A//www.aim.com/get_aim/congratsd2.adp&triedAimAuth=y&promo=380464 here].</FONT>
<br />
<FONT STYLE='font-size: 80%'><SPAN ID=buddyicons>5</SPAN> - Newer "extended status" buddy icons are working fine, but icon handling in older clients where the clients exchange icons directly is broken.</FONT>
<br />
<FONT STYLE='font-size: 80%'><SPAN ID=groupchat>6</SPAN> - Something causes outgoing messages to the chatroom to cease functionality after a certain amount of time, amongst other problems.</FONT>
==Installation==
===Before You Start===
Before you install, you need to make sure you have the following things:
* A [http://www.jabber.org/ Jabber] server; Known to work with:
* Optional: [http://sourceforge.net/projects/mysql-python mysql-python] for [http://www.mysql.org mysql] database backend
* Optional: [http://www.pythonware.com/products/pil/ Python Imaging Library (PIL)] for avatar support (note '''disableAvatars''' option if you don't want them)
* Optional: [http://python-ldap.sourceforge.net/ LDAP client API] for LDAP authenticated registration support (see '''authRegister''' option)
Also note that there may be a [[#Tutorials|tutorial]] to walk
you through installation and configuration.
If you are planning to use the subversion repository, please note that the Repository is reachable via the subversion protocol, not via http. Make sure that port 3690 is not firewalled. Alternatively, you can download a tarball of the current repository [http://www.blathersource.org/project.php?projid=pyaim-t here].
===Transport Configuration===
After untarring the distribution, your first task is to create the transport
configuration file. The easiest way to do this is, in the root of the
distribution, copy '''config_example.xml''' to '''config.xml''', and edit '''config.xml'''.
The configuration options should be fairly self explanatory. However, if you
need some assistance, check out the [[#Configuration|Configuration]] section.
If you are upgrading from a previous version, you should always look over '''config_example.xml''' to see what options may have been added, removed, or changed.
===Spool Setup===
There are multiple 'drivers' for the transport's spool. The default and most basic is called '''xmlfiles''', and is capable of automatically converting the spool that the [http://aim-transport.jabberstudio.org/ c-based aim transport] uses. If you are migrating from an earlier version of the c-based aim transport, you can either point the '''spooldir''' variable at the location of the old spool (and make sure to also set '''jid''' to the same jid the old transport used), or you can copy of the c-based transport's spool directory to a new location pointed to by '''spooldir'''/'''jid'''. There is also a tool to [[Migration Tool|convert]] between different spool drivers, including the ability to convert a PyAIMt spool into one compatible with the c-based aim transport. If you are not migrating, simply 'mkdir' the spool directory at '''spooldir'''/'''jid''' and make sure the transport will have access to write to it.
The available spool drivers are described as follows:
<div class="indentedsection">
====xmlfiles====
This is the default driver, and stores the spool files in a "hashed directory structure". The layout is designed to provide fairly good performance. All files are in XML format and are stored as plain text. The driver has one option, '''format''', which can be set to '''encrypted''' to shroud passwords. See '''config_example.xml''' for an example of how to enable this option.
====mysql====
This driver stores the spool inside of a MySQL database. There is a [[MySQL Tutorial|tutorial]] available that explains the procedure for setting up the MySQL database.
====legacyaimtransport====
This driver stores the spool in the same format the [http://aim-transport.jabberstudio.org/ c-based aim transport] uses. '''Please note:''' This driver is not intended to be used regularly. It only really exists to allow the [[Migration Tool|migration tool]] to convert between newer spool formats and this spool format at will. If you use this as your driver, a lot of functionality will be lost. (such as caching of known avatars)
====template====
This driver is not a real driver. It is a stub that is intended to provide a starting point for anyone who wants to write their own driver for another spool file database format. If you write such a driver, please submit it back to [[User:Jadestorm|Daniel Henninger]] so he can include it in the main distribution.
</div>
===Jabberd 2 Setup===
You can set up the transport for Jabberd 2 in two different manners. One involves using Jabberd 2's own component protocol and SASL, and the other involves adding an alias for the aim chatrooms jid but otherwise doing little else.
<div class="indentedsection">
====Setup using component protocol and SASL====
To use this setup method, you will need to add a user (or use an existing one) to Jabberd 2's router-users.xml config file. By default, this file has one use in it named '''jabberd'''. While I do not believe you have to, I would recommend that you create a separate user for the transports, like:
<pre>
<user>
<name>pytransport</name>
<secret>mysecret</secret>
<user>
</pre>
You will likely need to restart Jabberd 2 at this point. However, afterwards, you can add '''useJ2Component''', set '''saslUsername''' to the same '''name''' you put in router-users.xml above, and set '''secret''' to match '''secret''' from router-users.xml in your config.xml file. The transport should connect to Jabberd 2 and bind as every jid it wishes to be. (ie, it will bind as '''jid''' and '''confjid''' from your config.xml file)
====Setup without component protocol or SASL====
If you do not want chatroom support, there is little or nothing you have to do. Just make sure that the '''secret''' is set to something your server is expecting. If you do want chatroom support, you will need to set up an alias in your router.xml Jabberd 2 config file similar to:
<service type="aim" jid="chatrooms.aim.myserver.org" name="AIM Transport Chatrooms">
<ns>jabber:iq:conference</ns>
</service>
</pre>
The entry in the browse section is optional - the gateway will work without it, but the users wont be able to see the gateway in the service discovery of your jabber server - the browse section specifies the content of the Service Discovery of your jabber-server.
'''Hint:''' The tool "xmllint" (Debian Users: It is contained in the package libxml2-utils) to check the syntax of your xml config file (and even to format it nice, using the --format option).
Make sure that the following configuration options are synced up in both
entries:
{| style="background-color: #b3cde7"
|-
| config.xml
| <=>
| jabber.xml
|-
| style="text-align: right" | jid
| style="text-align: center" | =
| style="text-align: left" | id
|-
| style="text-align: right" | jid
| style="text-align: center" | =
| style="text-align: left" | host
|-
| style="text-align: right" | secret
| style="text-align: center" | =
| style="text-align: left" | secret
|-
| style="text-align: right" | port
| style="text-align: center" | =
| style="text-align: left" | port
|-
|}
After you make all of those changes, restart your Jabber server, and start
The first thing you will need to do is to configure Wildfire so is willing to accept connections from external components. To set this up, go into Wildfire's admin (web) console and look for '''External Components'''. Once you have opened this category, make sure that '''Service Enabled''' is set to '''Enabled'''. Make note of the '''Port''' and '''Default shared secret''' (and maybe change them if you want). You will use those in the transport '''config.xml''' file. There are more advanced things you can do here as well, but I am not getting into them here. Once you have everything they want you want it, click '''Save Settings'''.
After you have saved your Wildfire settings, edit your transport '''config.xml''' (you may need to copy '''config_example.xml''' to '''config.xml''' first) and make sure that the '''jid''' is set to whatever jid you want the transport to answer as, make sure that the port is set to the same thing you noted from the Wildfire admin console, and make sure '''secret''' is the same as the '''Default shared secret''' from the Wildfire admin console. There are plenty of other options in the transport config file. I would recommend looking over the entire file and adjusting variables as they seem appropriate. They should all be explained in the config file, but also here in the online documentation.
After you finish with the config file, you should be able to fire up the transport and after it connects you should see it listed in Wildfire's '''Sessions''' tab, under '''Component Sessions'''.
'''Warning:''' At this time, groupchat support does not work under Wildfire. There is not a way for the transport to identify itself as more than one jid. However, the functionality is available in the dev version of Wildfire and PyAIMt, so stay tuned!
Configuring the transport for Ejabberd is similar to Jabberd 1, except that you most likely will not have to restart your jabber server to add the transport. A detailed tutorial for setting up the transport with Ejabberd is provided [http://ejabberd.jabber.ru/pyaimt here]. Instead of maintaining similar documentation in two places, we are simply deferring to their documentation.
Most of the configuration options available are strictly to configure
interaction between the transport and your Jabber server. There is a
'''config_example.xml''' file that exists in the
root of the distribution that you can start with. You
should end up with a '''config.xml''' file in the
root of the distribution. In other words, copy
'''config_example.xml''' to '''config.xml'''
to get started. Below are explanations of all of the current configuration
options.
===Options===
{| class="optionslist"
|-
| '''jid'''
| This is the Jabber ID that you would like to associate with this transport.
|-
| '''confjid'''
| This is the Jabber ID that you would like to associate with this conference room/chatrooms of transport. Should not be the same as '''jid'''.
|-
| '''compjid'''
| This is the component Jabber ID of the transport, for XCP clustering.
|-
| '''spooldir'''
| This is the location of the spool directory associated with this transport. This should -not- include the JID as the actual spool used is this config option + "/" + '''jid'''.
|-
| '''pid'''
| This is the full path to a file you would like to store the transport's PID in.
|-
| '''mainServer'''
| This is the hostname/ip address of the Jabber server this transport is to connect to.
|-
| '''mainServerJID'''
| This is the jabber id of the Jabber server this transport is to connect to.
|-
| '''website'''
| This is the web site that an end user can visit to find informamtion on your Jabber server.
|-
| '''port'''
| This is the port over which this transport is to communicate with the Jabber server.
|-
| '''webport'''
| This is the port over which the web admin interface is to respond.
|-
| '''secret'''
| This is a shared secret between your Jabber server and this transport.
|-
| '''<strike>websecret</strike>'''
| <strike>This is a password used to access the web admin interface.</strike>
|-
| '''lang'''
| This is the default language you would like this transport to us when sending transport-initiated messages back to the user.
|-
| '''aimServer'''
| This is the hostname of the AIM-compatible login server you want the transport to connect to.
|-
| '''aimPort'''
| This is the port on the AIM-compatible login server you want the transport to connect to. Note that AOL's own servers will apparantly answer on all ports. At this time, there is a bug where buddy icons do not function correctly if you do not use port 5190.
|-
| '''socksProxyServer'''
| This is the hostname/ip address of a socks5 proxy server that the transport is to connect to AOL's OSCAR servers through.
|-
| '''socksProxyPort'''
| This is the port of a socks5 proxy server that the transport is to connect to AOL's OSCAR servers through.
|-
| '''sessionGreeting'''
| Set this to a welcome message you want your users to see upon logging in. Leave blank/unset if you want no welcome message.
|-
| '''registerMessage'''
| Set this to a welcome message you want your users to see upon registering with the transport. Leave blank/unset if you want no welcome message.
|-
| '''crossChat'''
| Enable this to permit chatting with ICQ users as well as AIM users.
|-
| '''disableRegister'''
| Enable this to disable registration with the transport.
|-
| '''enableAutoInvite'''
| Enable this to trigger the transport to ping all known users upon startup, triggering them to log in if they're available.
|-
| '''disableXHTML'''
| Enable this to prevent any XHTML support from being used. This is typically useful if you are having problems with the XHTML support or you have an adversion to 'stylized' messages.
|-
| '''disableMailNotifications'''
| Enable this to prevent the transport from requesting to be notified of new mail associated with a user's AIM account.
|-
| '''disableDefaultAvatar'''
| Typically, PyAIMt will set a default avatar for any user who does not have an icon, or whose icon can not be handled by the transport. By enabling this option, you can leave the icon blank/empty when these situations come up.
|-
| '''admins'''
| JIDs listed within this tag will have access to restricted ad-hoc command functionality.
|-
| '''reactor'''
| Choose between version low-level reactors that drive the base functionality of the transport. Choices are: poll, select, kqueue, epoll, and default. For Linux 2.6, epoll is recommended because it is way faster. Follow [http://www.kegel.com/c10k.html this link] for (very) verbose information about this subject. For FreeBSD, kqueue is recommended. If you explicitly choose default, you will get the default reactor for that OS. (this is important for Windows) If you do not specify this variable, the transport will attempt to detect the best option you have available. Under Windows, this detects the wrong thing, unfortunately.
|-
| '''xdbDriver'''
| Choose between various methods of storing the transport's database. Current choices are: xmlfiles (default), mysql, and legacyaimtransport (backwards compatibility with c-based aim-transport). Note that some drivers have associated configuration options explained in '''config_example.xml'''.
|-
| '''avatarsOnlyOnChat'''
| Enable this option if you only want avatars to be exchanged when two users are communicating with each other directly. In other words, no icons will be retrieved unless there is a conversation going on.
|-
| '''disableAvatars'''
| If you do not have a functional Python Imaging Library (PIL) installed, or you simply do not want avatar support, you can enable this to kill support for avatars.
|-
| '''useXCP'''
| This enables protocol extensions that Jabber.com's server contains.
|-
| '''saslUsername'''
| This, combined with '''secret''', are the credentials that will be used when doing a SASL bind with a Jabber server.
|-
| '''<strike>useJ2Component</strike>'''
| <strike>This enables protocol extensions that the JabberD2 server uses to allow binding as one or more JIDs.</strike>
|-
| '''useComponentBinding'''
| This causes the transport to bind to whatever JIDs the transport intends to answer as. This process is explained via [http://jabberd.jabberstudio.org/dev/docs/component.shtml Jabberd2's component protocol] and will be formed into a forthcoming JEP submission. Wildfire supports this without SASL whereas Jabberd2 requires SASL (and hence, saslUsername to be set).
|-
| '''messageArchiveJID'''
| This enables message archiving ([http://www.jabber.org/jeps/jep-0136.html JEP-0138]). Set to the JID of something that implements this protocol.
|-
| '''authRegister'''
| This causes the transport to require external authentication before being permitted to register. Right now, only LDAP is supposed for this functionality. All of the related fields specified in config_example.xml are required to be filled out for this functionality to work. Please note that, to the end user, this will look like they are having to register twice.
|-
|}
==Tutorials==
Sometimes helpful folk provide tutorials on how to set up PyAIMt for
specific situations. Any tutorials I am made aware of, or that we write up, are
listed below:
* [http://ejabberd.jabber.ru/pyaimt Configuring PyAIMt to work with ejabberd]
* [[MySQL Tutorial|Configuring PyAIMt to use the MySQL XDB backend]]
* [[Remote Access|Configuring PyAIMt to be accessible from remote servers]]
==Prepackaged versions==
For Debian users, there is an apt repository which contains all the Python transports.
Add this to your /etc/apt/sources.list to use it:<br>
deb http://www.spectron-msim.com/debian/ transports main<br>
