User Guide

From PsiWiki

An alphabetical index of all User Guide topics can be found in the User Guide Category. The below is the same information organized more like a book. When linking to this page, please link to the sub-pages themselves, not this table-of-contents page.

Contents 1 Roster 1.1 Status 1.2 Authorization 1.3 Accounts 1.4 Contacts 1.4.1 Self Contact 1.4.2 Adding Contacts 1.5 Groups 1.5.1 Hidden Group 1.6 Gateways (Transports) 1.6.1 About Gateways 1.6.2 Connecting to the proprietary network 1.6.3 How does a gateway work 1.6.4 Connecting to an IRC Network 1.6.5 Frequently Asked Questions 1.6.5.1 Gadu-Gadu users 1.6.5.2 FAQ 1.6.6 Useful links 2 Chats 2.1 Formatting 2.2 Using Tabbed Chats 3 Messages 3.1 Formatting 4 GroupChat 4.1 Inviting friends 4.2 Receiving Invitations 5 Service Discovery 5.1 About Service Discovery 5.2 Browsing using Service Discovery 5.3 Server components 5.4 Actions 5.4.1 Register/Unregister 5.4.2 Search 5.4.3 Join 6 Profiles 6.1 What is a profile? 6.2 How is a profile used? 6.3 Who should use/add new profiles? 6.4 Creating a profile 6.5 Profile options 7 Accounts 7.1 Resources 7.2 Managing Accounts 7.3 Proxy Configuration 7.3.1 Proxy settings 7.3.2 Proxy types 7.3.3 Setting up a proxy 7.4 Account Properties 7.4.1 Ignore SSL warnings 8 File Transfer 8.1 Introduction 8.2 Binary Streaming Methods 8.2.1 In-Band 8.2.2 Out-Of-Band 8.3 Configuration 8.4 Sending files 8.4.1 Transfer Manager 8.4.2 Technical Details 8.4.3 Encryption 8.5 Foreign Networks 8.6 The Future 8.7 External Links 9 History 10 GnuPG 10.1 Setting up GnuPG 10.2 Creating Key Pairs 10.3 Configuring Psi 10.4 Assigning GnuPG keys 10.5 Using Encryption 10.6 Usage 10.7 Troubleshooting 11 Psi Options 11.1 Application 11.2 Chat 11.3 Events 11.4 Status 11.5 Appearance 11.5.1 Emoticons 11.6 GroupChat 11.7 Sound 11.8 Advanced 12 Iconsets 13 Types of Iconsets 13.1 System Iconsets 13.2 Roster Iconsets 13.3 Emoticon Iconsets 14 Contributions 15 Adding a new (Roster) Iconset 16 Advanced Features 16.1 The XML Console 16.1.1 Starting the XML console 16.1.2 Sending custom XMPP code 16.2 Command-line Options 16.3 Editing config.xml 16.3.1 Finding config.xml 16.3.2 Changing roster item order 16.3.3 Using Psi installed on removable USB device 16.4 Managing Custom (self-signed) SSL Certificates 16.4.1 Background 16.4.2 The Problem 16.4.3 The rootcert.xml File 16.4.4 Manual Process

Roster

The roster is the window that lists your contacts. In some other Instant Messaging programs it's called a contact list, for obvious reasons.

This is the center of your experience with Psi, and it is from here that your session is controlled.

Status

You can set your status to enable other users who have you in their roster to see your availability at any given time. You can do this in various ways: you can right click on the 'account header' (the entry in your roster with a padlock icon next to it, which will display the name that you gave to your Psi account) and choose 'set status' from the menu that appears; you can choose your status using the status selection button that appears as default at the bottom of your roster; or if you have configured your roster's apearance to display the different status buttons individually, you can simply select the relevant status. You can choose between: Online, Away, Not Available, Do Not Disturb, Free for Chat, Invisible and Offline. There is the option to add a personalised message to your status display, should you wish to give any details about why you are away/what you are doing etc. This you can do by inserting text into the pop up window that appears when you select your status. As well as this, there are a selection of 'preset' status messages that you can either use, or modify to make them more personal to you. IF you choose to display a status message, other users will see you on their roster as being away/not available etc at a glance, and will be able to read your status message when they hover their cursor over your name in the roster.

Likewise, you can view your contacts' status and status messages - the icon next to their name changes according to their status for 'at-a-glance' information, and you can view any status message they may have set by hovering over their name.

Authorization

Authorization is required to be able to view a contact's status. What does this mean? Basically that if neither you nor the other contact has authorization, you cannot see each other. If only you have authorization, you can see their status and they can't see yours; if only they have authorization they can see your status and you can't see theirs. If you both have authorization, you can see each other.

How do you obtain authorization? When you add a contact, you will have the option both to add authorization to, and request authorization from the contact. When you are added to someone's roster your permission will be requested to grant them authorization.

Although authorization is needed to see a contact's status, it's quite possible to have many contacts in your roster without authorization, and to chat and message them quite normally.

Accounts

Contacts

Your contacts are the names that appear in your roster, also known as the people with whom you communicate using Psi. As well as their names/nicks the roster also displays information pertaining to their status/online presence. You can add a contact to your roster, remove a contact, and you can also rename a contact if you wish (bob@jabber..... could be changed to Bob for example).

Self Contact

Psi has the possibility to show in the roster your own contact. This is particularly useful if you have more resources.

The self contact can't be renamed. It appears in the roster with the Nickname you have entered the VCard.

Adding Contacts

You can add contacts to your roster using the "Add a contact" dialog available in the Psi Menu (click on the Psi button).

If you want to add contacts over a transport, you need to follow these extra steps first

1. from the services dropdown list select your transport
2. Psi will initially try do use Service ID translation to "see" how Jabber IDs for that specific transport should look like
   1. In case of success
      1. you'll be asked to enter the ID (as the of your ) of the other user in the Service ID box
      2. click "Get Jabber ID"
      3. the Jabber ID will be automatically filled with the ID of the user over the transport
   2. In case of failure
      1. you'll have to figure out how the Jabber IDs are formed out for that transport (usually: username@transport_jabber_id // Example: myYahooID@yahoo.myserver.net)
   3. enter this ID in the Jabber ID box

Steps for adding any kind of contact:

1. Make sure the Jabber ID box is not empty
2. Name your contact (fill the Nick field)
3. Select a group to put your new contact
4. You'll probably want to select "Request authorization when adding"
5. Click "Add"

You're done!

Groups

Psi does not support yet in the interface having users in multiple groups, although it is technically possible in Jabber.

Psi will show correctly the users in multiple groups if these changes have been performed in some other client.

If you feel adventurous, start the XML console and send the following piece of XMPP (Jabber) code:

<iq type="set" id="some_id" >
 <query xmlns="jabber:iq:roster">
  <item name="Contact Name" jid="contact_jid@server.org" >
   <group>Group 1</group>
   <group>Group 2</group>
  </item>
 </query>
</iq>

Don't forget to modify:

• Contact Name to the name you want your contact to have when appearing in Roster
• contact_jid@server.org to your contact Jabber ID
• Group 1 and Group 2 to the name of the groups you want the contact to appear.

You will have now Contact Name in both Group 1 and Group 2. If you want more groups simply multiply the <group>...</group> line to add all your wanted groups. If you want less groups, send the code with a new set of groups. Every time you have to enter all the groups you want the contact to appear in.

You can also enter no group. The contact will appear in the "General" group in Psi.

Hidden Group

This is a normal group in the Jabber account which can be hidden by Psi (also available as a normal group in other Jabber clients).

It is special for Psi because it can be hidden. Why would you do this? It is a very convenient way of keeping bots hidden, even though they are online. Also, if you have multiple contacts in your roster of one single user, you could hide some of them with the 'Hidden' group and leave only the most accessible one visible. In case there is an emergency, the 'Hidden' group can be made visible and used as a normal group.

In order to make the 'Hidden' group visible/invisible, go to the 'View' menu and check/uncheck 'Show Hidden' menu item.

If you want to move a user to/from the 'Hidden' group just like you do with any other group.

Gateways (Transports)

About Gateways

Gateways, also known as Transports, are Jabber components used for interacting with proprietary networks (instant messenger networks, SMS etc.).

Typically, gateways are used as translators between different types of instant messengers. If you are using Jabber but a friend uses MSN you can use a MSN gateway that will allow you to send messages to, and chat with, your friend on MSN.

You can choose whether or not to display gateways on your roster by clicking the gateway icon at the top of the roster. By displaying the gateways, as with your contacts, you can view the status of a gateway - if a gateway is offline the contacts in your roster for whom that gateway applies will appear as offline also. For example, if the MSN gateway is offline, your MSN contacts will appear as offline as well.

Connecting to the proprietary network

1. Before you can use a gateway you must have an account with the selected IM. For example if you want to communicate with friends on MSN you must have created an account on the MSN website. The advantage of using Psi is that it can communicate with all of the major IM networks in one place.
2. If you are on a server that provides a gateway you just need go to the next step. If your server does not provide the gateway you need you have to search for a different server, that provides the gateway and allows users who are not using this server to register. Many servers block users from other servers and very often google accounts are blocked especially. Look e.g under [1] for a server that has a coloured icon for your needed gateway.
3. You have to browse using Service Discovery to the server which hosts your Gateway. You may want to enter the address of a different server to get access to different gateways. If you use gateways only on your server, you just need to open Service Discovery and they will come up right away in the window, without modifying the address in the address bar.
4. You need to let the gateway know your username and password for the proprietary network. This is done through a process called registering with the gateway. Once you have registered with the gateway, the contacts from the proprietary network should be pushed to your roster, if the gateway is functioning right.

How does a gateway work

The gateway (transport) functions like this:

1. you log into the Jabber account
2. the server sends your presence info to anyone in your roster (contact list) (this includes Gateways, which are just normal contacts, only displayed differently)
3. once a gateway receives the presence information it logs into the proprietary network (only if you are registered with the transport)
4. the gateway sends to your server the presence information of all the gateway contacts

The easiest way to not make the transport log automatically, is to remove authorization (Right click on the transport > Authorization > Remove authorization from). This will save you from entering registering the transport over and over again. You'll have it registered, but "blind", since you've removed its authorization and it won't receive any presence information from you (=it won't see you).

Connecting to an IRC Network

1. Perform a Service Discovery.
2. Register with the IRC protocol.
3. Bring up the Multi User Chat dialogue.
4. Your hostname is that of the transport you have registered.
5. The room name is entered in one of the forms:
   1. room%server.domain.tld (for ejabberd's irc gateway)
   2. #room%server.domain.tld (for pyirct ad-hoc server connections)
   3. #room%serveralias (for pyirct pre-registered server connections).
6. If you're using ejabberd's irc gateway, your nickname cannot be changed using the normal IRC /nick command once connected so choose it carefully if you have not registered the name previously.
7. If your nickname has been registered previously nickserv will contact you. Simply type "identify password" in a message to it in order to identify yourself.

Once connected you will receive server messages in new windows, these hosts will appear as temporary contacts in your roster. After a short period of time, dependant on the IRC server to which you are connecting, the requested room will open in a new window.

Frequently Asked Questions

We have a special section on the FAQ Page about Gateways. Make sure you check it out.

Gadu-Gadu users

Please check this Forum topic for more help on setting up a Gadu-Gadu gateway.

FAQ

Useful links

• Jabber MSN Gateway User Guide - PyMSN transport (make sure you're not using the old C MSN transport)
• Jabber ICQ Gateway User Guide - PyICQ transport
• Jabber AIM Gateway User Guide - PyAIM transport
• Jabber RSS Gateway - pyrss transport
• Jabber RSS Gateway - RSS transport (Java Implementation)

Chats

Formatting

Psi supports basic formatting for both chats and normal messages.

Formatting rules:

• *bold*
• /italic/
• _underline_

You need to enable emoticons if you want formatting to be enabled. If you don't want emoticons to be showed, clear the list of emoticon sets.

Psi has planned support for XHTML-IM, a Jabber Enhancement Proposal which describes the allowed HTML set to be used in XMPP (Jabber). The port to Qt4 (planned for Psi 0.11) should ease up the implementation. New features are to be added after 0.11.

Using Tabbed Chats

Each chat is placed inside a tab. In a window, you will find a group of chats called tabset (a set of tabs).

Mouse actions (LMB, MMB, RMB - left/middle/right mouse button):

• LMB double-click - detach tab
• MMB drag inside the same tabset - move tab inside the same tabset
• LMB drag outside the current tabset, into another tabset - move tab into another tabset (it turned out not to be working in Windows, although it was coded with no platform specific code)

Keyboard shortcuts:

• Ctrl+Page Up/Down = previous/next tab (like in Firefox, iChat)
• Ctrl+W = close tab (like in Firefox)
• not yet implemented: Psi 0.10 is also planned to support Ctrl+Tab/Ctrl+Shift+Tab for previous/next tab - like all Windows applications

Messages

Formatting

Psi supports basic formatting for both chats and normal messages.

Formatting rules:

• *bold*
• /italic/
• _underline_

You need to enable emoticons if you want formatting to be enabled. If you don't want emoticons to be showed, clear the list of emoticon sets.

Psi has planned support for XHTML-IM, a Jabber Enhancement Proposal which describes the allowed HTML set to be used in XMPP (Jabber). The port to Qt4 (planned for Psi 0.11) should ease up the implementation. New features are to be added after 0.11.

GroupChat

Multi User Chat(MUC) is the next generation of the GroupChat protocol. MUC is implemented starting from Psi 0.11. And Psi 0.10 is minimally compatible with MUC rooms (with several (many) limitations).

You can join a multi user chat by clicking the Psi menu, then selecting Join Groupchat. The Join Groupchat dialog appears (shown on the right).

If you have more than one Jabber account, you can select from the "Identity" list which one to use when you connect to the Groupchat.

Enter the name of the Jabber Conference server into the Host field. Note: Not every Jabber server runs the Conference service. If you type in a chat room that doesn't exist, it will be created. Type in a nickname that you want to be known as during this chat session. If you have previously been to this chat room, you can select it from the "Recent" list.

Shown on the left is a chat room called jdev - the Jabber developers room. You can can see the list of people on the right hand side, the chat area on the left, and text entry at the bottom.

If you want to change the topic, click the Topic button. To quit the multi user chat, simply close the window in the normal way.

Inviting friends

You are able to invite your friends to join a multi user chat room that you are already in. Simply press the right mouse button on their name, point to Invite to, and click the room you want to invite them to. The example on the left shows me inviting Justin to the chat room jdev that I joined above.

Receiving Invitations

The dialog shown on the right is what you see when someone sends you an invitation. It appears just like a regular message, but with a special attachment. Don't click the link in the message, double-click the attachment instead. It will then open the Join Groupchat dialog shown at the top of this page, with the details of the Groupchat room you have been invited to. Simply type in a nickname and click the Join button.

The method of receiving invitations will be improved in a future release.

Service Discovery

About Service Discovery

Service Discovery allows you to:

• add the ability to talk to friends who use other instant messengers
• find a friend who uses Jabber
• create or join a conference room where multiple people can chat together
• other things, as Jabber is an extensible protocol and anything can be added in the future

Generally speaking, the Service Discovery dialog will allow you to:

• browse different servers/components, displayed in a tree (the root of the tree is the address you have typed in the Address Bar)
• do specific actions on the nodes of the tree, depending on their type/capabilities

Browsing using Service Discovery

1. Click the "Psi" button or right click the account name in the roster window.
2. Select Service Discovery, the Service Discovery window opens.

The Address drop down list shows the Jabber server you are currently connected to. You can also enter the address of another Jabber server (to find a list of open Jabber servers look at jabber.org).

Server components

Server components are usually the first root child nodes listed when browsing a Jabber server.

Most known server components are:

• Jabber User Directory (JUD) - stores information on jabber users
• Multi User Chat (MUC) - allows multiple people to chat together
• Gateways - allows interaction with proprietary (IM) networks

Depending on their functionalities, you can perform several actions on them.

Actions

Actions can be found:

• in the toolbar
• in the context menu (right click) of each node displayed

They may appear disabled if a certain functionality is not advertised. It may happen for some components not to work correctly and not advertise correct functionalities. Contact the server administrator or use a similar component on another server.

Register/Unregister

Some components provide the possibility to register with them. Once registered, the components will appear in the roster just like any other contact, but in a special group called "Agents/Transports". You would be able to do with the component the same actions you do with a normal contact, such as chatting - some components even "react" to commands sent via chat messages.

Typical components providing this action: Gateway, Jabber User Directory

It's possible to unregister a service (Psi considers all JIDs without user names as services) if you have it in your roster, and you delete it using normal GUI actions. Then Psi silently tries to unregister your service in the background. It's also possible to manually unregister service, but you'll currently need to use XML Console. It actually consists of registering, but with no information in all fields (empty fields).

According to Peter Saint-Andre from jabber.org you can manually unregister/deregister from a gateway or transport service by entering the following statement into Psi's xml console:

<iq type='set' to='icq.jabber.org'>
<query xmlns='jabber:iq:register'>
<remove/>
</query>
</iq>

NB: Please note that icq.jabber.org is just an example. Make sure you replace it with the service you want to unregister from!

Just to make sure you can also remove the authorisation. To do so, enter this query (again, replace icq.jabber.org with the service or gateway that you are using:

<iq type='set' to='icq.jabber.org'>
<query xmlns='jabber:iq:roster'>
<item jid='icq.jabber.org' subscription='remove'/>
</query>
</iq>

Search

Typical components providing this action: Jabber User Directory

Join

Typical components providing this action: Multi User Chat

Profiles

What is a profile?

A profile is a set of preferences that reflect the particular way you configure Psi for your personal use. By default Psi creates a profile for you during installation (Windows XP) or at first start-up (MacOS X) when you are asked to provide your Jabber Account User details. You can create more than one user profile.

How is a profile used?

The profile is stored on your computer's hard drive. It contains your Jabber ID (or multiple IDs) and determines which of these are enabled. It also remembers how the options have been configured, such as default actions, appearance (icon sets etc.), pre-set status messages, sounds etc.

Who should use/add new profiles?

Most Psi end-users will only need the one profile even if they have multiple Jabber IDs. However, profiles are useful when more than one person uses Psi on a single computer OR when you are using Psi in different contexts (work, social, testing).

Swapping between different profiles can be a lot easier than logging off your various Jabber IDs. When you start Psi all your Jabber IDs go "online". Sometimes you don't want all your contacts to see that you've come "online" when you are busy working.

Creating a profile

(imported from psi.affinix.com/psi_docs - also needs screenshots) When you first launch Psi, you will be presented with the Open Profile dialog (as shown in the image on the right). Click the Profiles button to begin.

A new window will appear, which is where you'll see your profile after it's created. Click the New button to create your first profile.

The Create Profile dialog will appear, as shown below. New Profile

Choose a simple name for your profile, such as your own name. Use only letters and numbers, no punctuation or special characters.

Jabber has two methods of sending messages to your contacts. Message is like ICQ, where they receive the single message, then click reply. Chat is like AOL, where the whole conversation continues in a single window that remains open. Select which one you prefer as your default. You are able to change this later if you change your mind.

If you'd prefer to see Smilie Face whenever someone sends you a :-), then check the box next to Enable Emoticons.

Click Create, and you will be returned to the Open Profile dialog. You will see that your newly created profile appears in the drop-down list. If this is the only profile you will use, tick the checkbox labeled Automatically open on startup. Click Open to select your profile for use.

Profile options

Accounts

Psi is one of very few Jabber-only clients (if not the only one) with the possibility to connect to more than one account at the same time.

Resources

Unlike other Instant Messaging networks, the Jabber network allows you to connect more than once at a time, from different places. To do this, every time you sign in, you label it as a different "resource". A resource is just a name. You might call one resource "home", another one "work" and another - "laptop". You assign each of those resources a Priority Number. When logged in multiple times, messages sent to you always go to the resource with the highest priority by default.

For example: you leave Psi logged in at home with Priority 1, and when you're at work you sign in with Priority 2. As your Work resource has a higher priority, messages be routed to work when you're at work, otherwise to home. You sign off when you leave work, and messages then get routed back to your Home resource. If you're signed in at both Home and Work, and get called out to another location, you might like to take a laptop with you. In this case you might sign in as Laptop (Priority 3) for when you're off site temporarily.

Managing Accounts

In order to add/modify/remove accounts from the current profile, you need to open the Jabber Accounts dialog:

1. click the Psi button (or open the 'General' menu)
2. select 'Account Setup' from the menu

To delete an account, use the General > Account Setup menu, select the desired account, and click the Delete button. You will then be asked if you want to delete the account only locally or on the server, too. Please note that you cannot delete an account by right-clicking on its icon in the GUI and selecting Modify Account.

Proxy Configuration

A proxy server is a computer network service that allows clients to make indirect network connections to other network services. More iformation on proxies can be found here.

Psi can use Proxy servers to facilitate the connection to the Jabber Servers through firewalls or in some special network conditions.

Proxy settings

The typical settings for the Proxy configuration are:

• Host (mandatory)
• Port (mandatory)

If Authentication is used (the "Use authentication" checkbox is checked):

• Username
• Password

Proxy types

HTTP "Connect"

very simple proxy protocol

SOCKS v5

About SOCKS protocol

HTTP Polling

this is used according to the specifications (JEP-0025) - the "Polling URL" is a specific setting for this type of proxy

Setting up a proxy

You can set up a proxy to be used for a specific account.

You just need to know the proxy type and the proxy settings - these are usually provided by your network administrator. Once you know this, follow the following steps:

1. in the Jabber Accounts dialog, select the account for which you need to enable Proxy support
2. click 'Modify'
3. in the 'Account Properties' dialog, open the 'Connection' tab
4. if you have any proxy set up, you can select it from the dropdown list
5. to add a new Proxy, click 'Edit'
6. in the 'Proxy Profiles' dialog, click new
7. change the type of the proxy and its settings
8. click 'Save'

TODO: integrate: http://nscsysop.hypermart.net/proxypac.html

Account Properties

Ignore SSL warnings

SSL certificates are used to offer encrypted communication between the client and the server.

There are servers which use self-signed SSL certificates. If your Jabber server is one of those, you may get an error like this:

The [servername] certificate failed the authenticity test.
Reason: Certificate is self-signed.

Psi is warning you that the certificate is not trusted. You should be able to connect by pressing 'Continue', however this will not work when you are registering a new account.

This is not a problem with Psi. This is a problem with your server's certificate. If you don't want Psi to warn you about an untrusted certificate, then the server administrator needs to get the certificate signed by a Certificate Authority (like Verisign).

If you are aware of the security issues and want to "trust" a self-signed certificate, for one thing, be sure you do trust the administrator. We've seen some server admins who are doing this as a hobby not a business and they don't wish to shell out cash for a properly signed certificate. (Hint, SSL certs are cheap now.)

If you still wish to use a self-signed certificate but don't want to get the warning on each login, you simply need to check this option (Ignore SSL warnings) in 'Account Properties' dialog for the account you wish to log into.

If you enable this option, be aware that it is easy for an attacker to send you another self-signed certificate (which will then be trusted), without you noticing it. Better explicitly install the certificate as a trusted certificate in Psi, and leave this option unchecked.

File Transfer

Introduction

File transfer with Psi depends like everything in Psi on the XMPP/Jabber protocol standards. To accomplish a file transfer, the sender and the receiver have to establish a connection which allows them to transfer binary data streams between each other.

Binary Streaming Methods

In XMPP there are two different methods defined to manage a binary data stream: in-band and out-of-band. Both are described below.

In-Band

In this method the data is sent in pieces on the same XML connection used for chatting.

Disadvantages

In this method all of the traffic flows inline over the Jabber server(s) to which the sender and the receiver are connected. This creates additional load on the Jabber server(s), making it potentially difficult for some high-traffic servers to support.

Furthermore, due to the inline nature of this method, the transfer speed is often much slower than through a direct (Out-Of-Band) connection.

Advantages

One advantage is a bit of anonymity between the sender and the receiver as only the server knows their IP-addresses. Furthermore, this method requires no special configuration on the client side, making the ability to send a file automatic among established peers.

Psi currently doesn't support data transfer over an In-Band data stream.

Out-Of-Band

In this method a separate connection is made for the binary data transfer. The clients themselves have to negotiate a working data stream/connection by sending each other their IP-addresses or the address of a proxy which is capable of connecting the partners together.

Disadvantage

This method carries added complexity when firewalls are involved between the sender and receiver. This can be minimized by using a proxy server, which also adds a layer of anonymity as the sender and the receiver need not know know each others IP-addresses.

Advantage

The transfer speed may be faster with this method. Throughput is generally limited only by the connection speed of the sender and receiver.

This is the only method Psi can currently use to execute a file transfer.

Configuration

A very important fact about file transfer with Psi is, that the client must be enabled to connect through a TCP port to an external computer. The default port for this is 8010 but it can be freely changed in the "Options" dialog available through the main menu of Psi. The option is called "Data Transfer Port" and resides on the "Application" tab.

Also on this tab is the option "Data Transfer External Address" which is to be used when Psi is not able to detect your external IP-address because you are connected to the internet through a router.

• If you have a static internet address you can fill it in this field.
• If your provider assigns a dynamic address to you everytime you connect to the internet, you should use a dynamic DNS name which contains your current IP-address. Two well known providers for free dynamic DNS are DynDNS.org and No-IP, a more scalable and also free offer is available at the german noxa.de Network (seems to be only accessible in german language at the moment).

For a file transfer to work, at least one of the partners has to be able to act as a server and is reachable through a direct connection on the defined Data Transfer Port. If you use a common home router, you could specify a static port mapping (often called "Virtual Server") to your computer or better use a triggered port mapping by defining the Data Transfer Port Psi uses (mostly 8010) as the trigger to bind exactly the same port to your local machine.

If everything above hasn't helped you, or is in anyway not possible on your network your last chance is to use a Data Transfer Proxy. You can tell Psi to use such a proxy by opening your "Account Setup" window through the main menu and modify your currently used profile. On the account modification dialog "Psi: Account Properties" go to the tab "Misc" and use the text-box labeled "Data Transfer Proxy" to set the proxy's address.

The most popular proxies are "proxy.jabber.org" (hosted by the Jabber Foundation) and "proxy64.jabber.ccc.de" (hosted by the Chaos Computer Club from germany).

Now you should be able to send and receive files. If not, your network configuration probably prohibits Out-Of-Band file transfer through Psi, or you might have missed something above.

Sending files

A transfer can be started by:

• right-clicking on a contact in your roster and then choosing "Send File"
• simply by dragging a file from the shell over a contact in your roster and drop it there.

This will open a "Send File" dialog in which you can:

• choose the account from which you want to send the file by using the drop down menu labeled "Identity"
• define the JID, including the resource to whom you want to send the file by editing the "To" text-box (should be automatically filled)
• specify a path to the file you want to send by using the text-box labeled "File" or the button near to it if you didn't use the drag & drop way to open the "Send File" dialog.
• optional: you can give your partner a description of the file you want to send her/him by typing anything into the "Description" text-box.

As soon as everything is correctly filled in you can start the negotiation and transfer process by clicking on the "Send" button. The animations states that Psi is still working on it's task. After the choosen receiver accepted the file and has choosen a path for the incoming file to save and if everything is configured the right way, the Transfer Manager will open and display a progress bar indicating the state of the file transfer. If the Transfer Manager doesn't appear either your partner has declined the file transfer or no data stream connection could be established. If the last case is right, read about Configuration paragraph.

Transfer Manager

The Transfer Manager window lists every file transfer and indicates the progress of every one. It will save every previous transaction until the "Clear Finished" button is pressed or the entry is individualy deleted by right-clicking and using the "Clear" option. Also transfers which are not yet finished can be aborted by right-clicking and using "Cancel". The Transfer Manager can be opened manually through the same named entry in the main menu of Psi.

Technical Details

After a file transfer request is sent to a Jabber user and this user accepts the request, both partners are sending their IP-addresses, DNS-names or those of a proxy to the partner. Both will then try to establish a connection through any of these. If this works a Out-Of-Band binary data stream connection is established and will be used to transfer the file.

Encryption

Warning: You should be aware of the fact that neither the file itself nor the file name and the file description will be sent encrypted although you are using OpenPGP encryption for chatting. If you want an encrypted file transfer you have to encrypt the file manually before transfer. On Windows you can use the your OpenPGP keys and Windows Privacy Tools (WinPT) or any other file encryption tool to do this.

Foreign Networks

A file transfer to different instant-messaging network through a Gateways (Transports) is not impossible. But it resides in the responsibility of the Gateway you use to offer this ability. At the moment there seem to be very less Gateways which support such a feature. Psi is only a XMPP-client and so it will never be responsible for this to work.

The Future

In the future it will most likely be possible to send files to contacts which are offline and also to receive file if the sender is already offline. This will be possible due to a WebDAV based storage service which the XMPP server has to offer to it's users. Actualy this process is discussed about at the Jabber Foundation as JEP-0129.

Also it is possible that in a later version Psi will support In-Band binary stream connections which would help all people who cannot use file transfer because of firewall and routing limitations.

Google Talk have implemented File Transfer via Jingle - this makes it far more likely that a file transfer will succeed. There is a Google Summer of Code 2006 Project to implement Jingle File Transfer in Psi.

External Links

• FTP Website Creation/Configuration

History

GnuPG

There are 2 types of encryption:

• end-to-end (e2e) encryption - Psi supports GnuPG
• client-to-server (c2s) encryption - Psi supports SSL/TLS for encrypted communication with the server

TODO: to be merged to be merged

Setting up GnuPG

(could be moved to something like... "Helper Documents")

No matter how well designed a messaging network is, it is often possible for someone to intercept and read your messages. Although we cannot stop the possibility of someone intercepting your message, we can stop them reading it by encrypting it.

Rather than re-inventing the wheel by developing encryption especially for Psi, we use a very fine encryption program called Gnu Privacy Guard (GnuPG). GnuPG is a free replacement for Pretty Good Privacy (PGP), and suits Psi better because it runs on Windows, Mac and Linux. To use encryption in Psi, you will first need to install and configure GnuPG.

First, download and install GnuPG. The method for doing this will vary depending on your Operating System. A correct installation of GnuPG on Windows will add a registry key that tells the system where gpg.exe is located. If you cannot open a command prompt window and run gpg.exe, then you will need to ensure that the gpg.exe executable is in your PATH. Refer to your Windows manual for how to change the executable PATH.

Creating Key Pairs

(could be moved to something like... "Helper Documents")

To use GnuPG, you will need to create something called a key pair. One key is public, you give this to your friends. When they message you, Psi encrypts their messages with your public key, and you unscramble it using your private key. Never give your private key to anyone at all, ever! By keeping your private key secure, your friends are guaranteed of your identity when they chat to you. To create a key pair, use this command:

gpg --gen-key

You will be asked the length of key to create; 1024 bit is fine. You will also be asked for a passphrase. This will be the password to your private key, so you'll need to remember it! You may also be asked for a comment; this is optional. You might also like to upload your public key to the keyserver network so that your friends can automatically download it, but that's beyond the scope of this document. Read your GnuPG documentation, or download a graphical GnuPG front-end like WinPT or GPGshell.

Configuring Psi

After you have configured GnuPG you must quit and restart Psi in order for it to detect the installation. Now, click the Psi menu and select Account Setup. Choose the account you wish to use encryption with, and click the Modify button. When the Account Properties dialog appears, select the Details tab and click the Select Key button in the OpenPGP section. If this button is greyed out, make sure you have restarted Psi since installing GnuPG. Select your private key and click the OK button. You will be returned to the Account Properties dialog and prompted for your private key password.

Assigning GnuPG keys

Using Encryption

Before reading this section, you should read the Setting up Encryption chapter. It explains how to set up GnuPG for use with Psi.

encrypt button To be able to send someone encrypted messages, you need to have their public key in your GnuPG keychain. For someone to be able to send encrypted messages to you, they need to have your public key. To learn how to import and export keys, read your GnuPG documentation, or use a graphical front end like WinPT or GPGshell.

If you have the public key of the friend you wish to have an encrypted chat to, and he has yours, then you can click the encrypt icon shown in the picture on the right.

chat encrypted After clicking the button, type and send a message. You may be prompted to select your friend's public key. Choose it and click the OK button. You will see a green message in your chat window, saying that encryption has been enabled (shown on the left). The lock icon will show a closed lock with a gold glow around it, indicating that GnuPG is successfully scrambling your chats.

The example above shows a chat being encrypted. You can also encrypt regular messages by clicking the same icon in the message window.

Usage

Once set up, end-to-end encryption can be used for encrypted Chats or encrypted Messages.

Troubleshooting

• FAQ: How can I avoid having to enter my GnuPG password each time I log in ?
• Investigating GnuPG Problems

Psi Options

Application

Chat

Events

Status

Psi has the possibility to change status automatically, when the computer is idle. This feature platform dependant and it might not work because of various platform-related reasons.

Windows

* the idle detection on Windows 9x,Me is embedded in the idleui.dll library, coming with Psi.exe in the same folder

* some anti-virus software might detect by error the library as dangerous object, even removing it from the system - the library does not have any malicious behaviour embedded (we have been notified that this happens with some versions of McAffe Antivirus)

MacOS

* nobody reported missing functionality on this plaform

Linux

* you need the XScreenSaver extension

* most distributions have this, but you might not have it or have it disabled

Due to the increasing demand of new features, the developers have planned a rewrite for the Status System. The design document with the new vision can be found here.

Appearance

Emoticons

Location: Psi Button > Options > Appearance > Emoticons

This is the page where you can the emoticons used by Psi in chats and messages.

• to enable emoticons, make sure you check 'Enable Emoticons' - this also enables Text Formatting.
• The list displayed here allows you to see the emoticons which will be used by Psi, by priority. What does that mean? Assuming you have 2 emoticon-sets mapping ":)" to 2 different images, when ":)" needs to be shown on the screen Psi will use the image in the top-most emoticon-set. If the first emoticon set does not have ":D" image for example, it will be looked in the following emoticon-sets and the first one found is displayed.

GroupChat

Sound

Include: http://forum.psi-im.org/post/25460

Advanced

Iconsets

If you are interested in creating an Iconset (system,roster,emoticons), we have created a guide to help you.

Types of Iconsets

System Iconsets

System iconsets decorate the program, and include icons and logos other than the roster iconsets and emoticons.

Roster Iconsets

Roster icons indicate the status of contacts and services.

To find the meaning of any icon in a roster iconset, look in Options, Appearance, Roster Iconsets, Show Details. The icon names listed there are defined in Creating Iconsets.

Emoticon Iconsets

Emoticons are combinations of text characters that form emotive icons.  :-)

Emoticon iconsets provide a menu of non-text images that have text equivalents. Point at one to see the text for it. Click on one to add it to a message. It may be shown as a similar non-text image by the recipient's software. An emoticon iconset may also be enabled simply as a graphic aid to selecting emoticons for use in plain text messages.

The jabber enhancement proposal for icon styles JEP:0038 has been deferred. It includes the jisp file format, which is in zip format and contains a folder that will add an iconset to Psi, if placed in the appropriate subfolder of your Psi installation.

Contributions

• JabberPL's Iconsets - Possibly the most complete list of iconsets
• Jabber Icons - a great collection of iconsets/emoticons for Psi
• Crystal Iconsets for Psi - Remko's Crystal Iconsets

Adding a new (Roster) Iconset

The following steps are based on MacOS X however steps 3-7 apply for Windows XP.

1. Locate the new iconset file you downloaded (see Contributions above).
2. Locate the Psi roster folder: right-click (control-click) on the Psi application icon and select show package contents, then burrow down until you come to the Roster folder ( Psi \ Contents \ Resources \ iconsets \ roster )
3. Add the new iconset file (name.jisp) to the roster folder
4. Launch Psi and select Preferences from the Psi menu
5. Choose Appearance from left side menu and then click on the Roster Icons tab
6. Select the newly placed icon set and click on OK.
7. You may need to quit and restart the Psi application to activate all changes.

For Linux:

1. Locate the Roster folder: I recommend the whereis command to find where Psi is (you might get multiple) the one that worked for me was /usr/share/psi/iconsets/roster.
2. Add the new iconset file (name.jisp) to the roster folder

follow steps 3-7 above.

For Windows:

1. Locate the roster folder (usually C:\Program Files\Psi\iconsets\roster)
2. Add the new iconset file (name.jisp) to the roster folder

follow steps 3-7 above

Advanced Features

The XML Console

You can watch the Jabber traffic in the XML console.

The outgoing packets are coloured differently than the incoming packets.

Starting the XML console

In order to turn on the XML console for an account, you need to get through the following steps:

1. right click on the account name in the roster
2. select XML console from the context menu
3. check 'Enable'

The XMPP (Jabber) should start flowing in the window.

Sending custom XMPP code

You can send a custom XMPP (Jabber) packet for an opened account connection. Steps:

1. Make sure the XML console is started
2. click 'XML Input...'
3. in the window which just opened, enter the custom XMPP packet
4. click 'Transmit'

Warning: if you send malformed XML/XMPP code the server might disconnect you

Command-line Options

--nocrash 

This option forces Psi not to write additional crash information if Psi was compiled with code to do so (and crashes). Unfortunately this does not prevent Psi from crashing!

--no-gpg (removed in 0.11)

Tell Psi not to use GPG at all

--no-gpg-agent (removed in 0.11)

Tell Psi to force GPG not to use an agent for passphrase management.

Editing config.xml

Finding config.xml

1. Close Psi.
2. Find your config.xml file, depending on your operating system:

   Linux, MacOS X and other Unices:

   $PSIDATADIR/profiles/profilename/config.xml

   Windows (all versions):

   %PSIDATADIR%\profiles\profilename\config.xml

   where:

   $PSIDATADIR or %PSIDATADIR%

   is the location of Psi's data files, see $PSIDATADIR

   profilename

   name of your profile in Psi

3. Make a backup of config.xml.

Changing roster item order

WARNING
Beware of the Psi bug FS#425. If you change <group>alpha</group> to <group>rank</group>, showSelf, showHidden, showAgents and showOffline will all be set permanently to "true". Changing this in config.xml file won't help. The values will be rewriten to "true" when you close Psi.

1. Locate your config.xml file, as described above. Make sure you've created a backup copy of the file.
2. Edit config.xml:
   1. Find

       <preferences>
         <general>
           <roster>
      

      tags in this file, you should have something like

        <sortStyle>
          <contact>status</contact>
          <group>alpha</group>
          <account>rank</account>
        </sortStyle>
      

      nearby.
   2. To change the way accounts are sorted, modify the value between <account> and </account> tags. Possible values are: rank (by manual rank) and alpha (alphabetic, default).
   3. To change the way groups are sorted, modify the value between <group> and </group> tags. Possible values are: rank (by manual rank) and alpha (alphabetic, default).
   4. To change the way contacts are sorted, modify the value between <contact> and </contact> tags. Possible values are: alpha (alphabetic) and status (status, default).
   5. If you want to change ordering of groups or accounts, find all occurences of <groupState> tags in config.xml. Note that groups are stored separately for each account (single <groupState> tag describes all groups within one account) and account is treated as a special group (having name starting with /\/ and ending with \/\).
   6. Each group and account has associated <group> tag, with rank parameter. Change the value of rank parameter. If group sorting rule for groups is set to rank, groups will be ordered with ascending ranks within the account.
   7. Accounts are also ordered with ascending ranks, if account sorting rule is set to rank.
   8. In both cases, if two or more groups (or accounts) have the same rank value, their order is not defined (usually, groups or accounts with the same ranks are sorted alphabetically).

3. Save config.xml file.
4. Run Psi again.

Using Psi installed on removable USB device

Windows XP, Windows Server 2003 (similar on Windows 2000): You may also create a special script, to boot your Psi from your removable USB device:

• place Psi anywhere on your USB device (fe. "\psi"). For example, just copy "Psi" from your "Program Files" directory
• create "psidata" directory inside "\psi" directory
• if you would like to use existing profile with USB device, copy your "profiles" to USB device "\psi\psidata"
• create the script (anywhere on the USB device), with extension ".cmd", fe. "psistart.cmd":

@echo off
set PSIDATADIR=\psi\psidata
cd \psi
start psi.exe

• save it and use it ;) It does not need any system reboot etc..

Managing Custom (self-signed) SSL Certificates

Background

Psi, up to and including v0.10, uses a cryptographic library called QCA1. Among other things, this library is used when connecting to a Jabber server over an SSL encrypted link. This works fine when the Jabber server has a certificate which was published by one of the "popular" root CAs(Certificate Authorities) that your Operating System already "trusts". However in most cases (see CACert for an exception) this costs money. Also it may not make sense to bother purchasing a certificate that has been signed by root CA if your server will not be accessed by anyone outside of your company's LAN.

The Problem

In theory, a smart hacker could create their own certificate, pretend it belongs to your bank, then spy on your internet connction and find out your password. When you use Psi to connect to a server that has what is called a "self-signed" certificate, Psi will popup a warning to this effect. This is intentional and important. It tells you that you may not wish to trust the encryption to this server, as no third-party has independently verified that this certificate belongs to this person or company. In a situation where you are connecting to a Jabber server that your company has setup for the employees to use, this error message is misleading and confusing to the end users.

The rootcert.xml File

The rootcert.xml file can be in a subfolder called certs in one of two places:

1. In the Psi program folder (e.g. /usr/share/psi/certs or c:\program files\psi\certs)
2. In your $psidata/certs folder (e.g. ~/.psi/certs or c:\documents and settings\hal\psidata\certs)

Psi ships with a rootcert.xml file that contains a default list of trusted certificates. This list of trusted root CAs is the same that Microsoft uses for Windows XP.

The format is simple, there is one <store> element in each file, with any number of <certificate> child elements. In each certificate, there is a <data> tag to contain the certificate data.

 <store>
   <certificate>
     <data>Lots of nice data here</data>
   </certificate>
   <certificate>
     <data>Data of another cert</data>
   </certificate>
   ...
 </store>

The data is DER+Base64 format, which is basically PEM but without the header, footer, or newlines.

Manual Process

1. acquire openssl executable (for Windows look here)
2. openssl s_client -connect server:5223
3. cut & paste text between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- into <data> tag
4. remove newlines within <data> tag (in fact newlines can stay. Make sure that no spaces exists

inside <data>MII...TDNqA==</data>, but newlines are okay. At least with Psi 0.10)