Getting Started


1. Preliminaries (getting Circle to work)
2. Configuration
3. Finding people
4. Finding and downloading files
5. Sending messages to people
6. Reading gossip
7. Text mode (circle -t)
8. Running goofey in the chat window
9. Using the apt methods

10. Using plug-ins


1. Preliminaries

RedHat 9.0 users:

Redhat 9.0 is shipped with a buggy version of glibc, that prevents Circle from behaving properly.
In order to get around this, it is possible to use the RawHide RPMs: glibc-2.3.2-37.i386.rpm or glibc-2.3.2-37.i686.rpm.

Gentoo GNU/Linux users:

The version of pygtk required to run Circle is currently masked as an unstable/testing package. There are two major methods that can be used to emerge the pygtk version that one needs:

Windows XP users:

To make circle (version 0.34) work on XP, you may have to delete the EMM32.dll file to get putty working.
To make circle (version 0.35) work on XP, you may have to add the directory C:\Program Files\GTK\2.0\lib to your Path environment variable

Circle and NAT:

If you have a direct connection to the internet, and you don't use BSD, you can skip ahead to the next section. Otherwise, welcome to the wonderful world of slightly broken internet protocols...

A computer behind a NAT (aka masquerading) network is something of a second class citizen. It can connect to other machines, but other machines can't connect to it. Circle needs other computers to be able to contact your computer, so we need to use a little trickery to get things working.

You have two options:

  1. run a proxy on a remote server (usually your firewall)
  2. configure your firewall to port forward UDP traffic for Circle

Circle can usually detect when you are using NAT, and will offer to run the proxy if there is NAT. You can also specify the exact options you want on the command line (run circle -h for a list of options).

The proxy

Running a proxy sounds like a lot of stuffing about and bother, right?

Wrong (hopefully...)

You'll need to have installed an SSH server and Python on the machine you want to run the proxy on, Circle can do the rest. When you run Circle, it will ask you for the machine you want to use as the proxy. It will then connect to it using SSH and send the proxy (which is a short Python program) over the network.

Configuring your firewall to pass Circle packets

Ok, the previous section was the easy way. This is the hard way.

If you can configure your firewall to forward all connection on the UDP port to your computer, circle should work. If more than one person is running circle within the internal network, each computer will have to be associated to a dedicated port in the 29610+ range.

You will then have to use circle with the -d option. Windows users, create a shortcut of the program, edit it with properties and add the -d to the command line

If your computer or firewall does some kind of packet filtering, please make sure it doesn't reject UDP packets for ports in the range 29610 to 29619.

Linux firewall IP table rule could look like (this is not for copy and paste)

	iptables -A GROUP -p udp -m udp --dport 29610 -j UDPACCEPT
iptables -A GROUP -p udp -m udp --dport 29611 -j UDPACCEPT
...
iptables -A PREROUTING -i eth0 -p udp -m udp --dport 29610 -j DNAT --to-destination 10.0.0.10:29610
iptables -A POSTROUTING -s 10.0.0.0/255.255.255.0 -o eth0 -j MASQUERADE

disclaimer:
Paul said that masquerading can cause problems, however I (Thomas Mangin) haven't noticed any problems using it.

disclaimer to the disclaimer:
Paul stands by his opinion. Masquerading will do weird ass stuff. You'll disappear and reappear in the network randomly.

BSD users

BSD users should make sure their packet filter allows the UDP packets sent by Circle through (Circle uses UDP ports 29610 to 29620). To do this you'll need to modify your packet filter's setup. Replace the following line in your /etc/pf.conf

	block in quick on $ExtIF from any to any
with
block in quick on $ExtIF from any to any
pass in quick on $ExtIF inet proto udp from any to any port 29609 >< 29621



Ok, thats the nasty network stuff done with, on to the fun part.

2. Configuration

Once you have Circle up and running, you'll need to enter some information about yourself so that other people can find you. You may also elect to make some files on your hard disk available to other people on the network, and specify a directory in which to place files you download.

To do this, choose the "Configure" option in the "Network" menu.

3. Finding people

To find a person, enter their name or username in the search box, and click "Find person". This will bring up a list of people matching your search.

Select the person you are looking for and click "Add to acquaintances". This will add their username to your list of contacts on the right hand side of the main window. It will also let you specify some options, such as whether you want to be told when they arrive and leave

Circle users are referred to by a nickname. This is usually the username they specified, but if two people have the same name, one of them will have a number stuck on the end to distinguish them. You may also change the nickname to a word of your choosing.

A person will be assigned a nickname if:


4. Finding and downloading files

To search for a file, enter some keywords or the full file name in the search box, then press the "Find file" button (just like an internet search engine). The Circle will then display a list of matching files and you can choose which ones you wish to download.

5. Sending messages 

A list of people you can send messages to is displayed in the right hand column of the main window. Click on the ">" arrow next to the person you want to talk to, then type in your message in the main area of the window and press enter.

As well as talking to people, you can talk on channels, rather like IRC. You will have been automatically subscribed to the "#welcome" channel. You can send a message to everyone on "#welcome" by clicking on the ">" arrow next to #welcome and typing your message as before.

You can do a number of other funky things related to messaging. For more information, see the chat commands page.

6. Reading gossip

The Circle has a system for gathering items of news posted by other Circle users, called gossip. It uses a trust network, rather like Advogato except that rather than raph et al being the root of the network, you are. What this means is you can individually tailor the news items you receive by specifying people you trust.

To specify that you trust someone, bring up their details window by clicking on their name or searching for them. Then tick the "Trust this person" checkbox and move the slider to specify the degree to which you trust them.

Once you have specified some people you trust you can view current news items using the "Show hot gossip" option in the "Gossip" menu. You can also post your own gossip using the "Post gossip" option, and other people will be able to read it.

7. Text mode (circle -t)

Circle has a text mode for people who are too manly to use graphical interfaces.
The text only interface can be started by running :

      circle -t

In text mode, you will need to use the weird commands described on the Circle commands page.

However, text mode isn't as capable as graphical mode (you cannot use Gossip in text mode).

All the Circle commands that exist in text mode can also be used in the chat window of the graphical interface.
In this window, it is also possible to click with your mouse pointer on the results returned by most Circle commands.

8. Running goofey in the chat window

If you don't know what goofey is, you don't need to read this section.

The Circle can run arbitrary shell commands in the main area of the window. Simply prefix the command with a double slash ("//"). So, for example, you can run goofey by typing:

//goofey

And of course you can do all the other goofey things goofey can do.

Note: Goofey does not work on masquerading networks, even if you start a proxy with The Circle.

9. Using the apt methods

(If you don't use Debian/Fink/Connectiva or something else that uses apt to download packages to install, then you can ignore this section -- though you should consider changing your operating system distribution to something that does use apt!)

The cftp and chttp apt methods will have been installed when you ran setup.py (or installed the Circle package if anyone ever gets around to packaging Circle nicely).

Edit your /etc/apt/sources.list file, changing all occurrences of ftp:// to cftp://, and all http:// occurrences to chttp://.

When you next do apt-get install foo, apt will first try searching the circle network for the package before falling back to the correspondingly-named non-circle method.

10. Using plug-ins

A number of circle plug-ins are provided in the plug-ins directory. In order to activate one of them, you need to put the corresponding file in your ~/.circle/plug-ins directory. The plug-in will be loaded on startup.

Have fun!