Getting Started

Preliminaries

BSD users: The default OpenBSD (and possibly other BSDs) packet filter configuration uses a stateful UDP filter rule that The Circle finds intensely confusing -- you will appear to others to disappear and reappear on the network randomly. To fix it read the firewall configuration section

If you have a direct connection to the internet, you can skip ahead to the next section.

Circle requirement

Each circle application needs to communicate with other nodes on the net. As other nodes will have to contact you when they want to exchange information, the circle need to be visible through a "real world" IP.

Each instance of circle use a single UDP port. The first instance on a machine will use port 29610, each next instance will use the next free consecutive port.

BSD users should make sure their firewall's packet fiter allows the UDP range used by circle adding this to the firewall rules. To do so, 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

Using circle behind a firewall

If you are NATted or behind a firewall, you have two ways to get circle running:

  1. execute circle proxy on a remote server (this can be your firewall)
  2. configure your firewall to port forward UDP traffic for circle

When circle detect that you are NATed (ie behind a firewall), circle's default behaviour is to offer to run some proxy code on another computer.

Using the proxy code

With the proxy code, circle use a computer with a real world IP to communicate with other nodes. This computer can be any computer on the internet which has an SSH daemon and is able to run python programs. If you use circle on a windows workstation, you will then need to download PuTTY and plink. Install them in the circle directory (ie: C:\Program Files\circle ).

You will need to create a trust relationship between your computers. To do so you will need to use the SSH client to connect to the server. SSH is designed to transmit encrypted information, this connection is used to established a trust relationship between the computers.

If you do not run putty/ssh at least once manually, circle will stall at boot time when you will run it if you use the proxy code bebind a firewall.

Once done, You can then run circle. Just enter your SSH information when requested:

	User: thomas@circle.slhan.org
	Pass: *********** (do not even try this one :p )

The Circle will then use SSH to start a small python program on the remote server that relays data between itself and the outside world.

Configuring your firewall to pass packet

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

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

What's with all those funny arrows?

The Circle for the most part behaves just like you would expect of a modern graphical application, but one thing that might not be clear at first is funny little arrows in the various windows. These show or hide parts of windows. For example clicking on many of the arrows will display some helpful information. Clicking again hides it.

Go on, click on a few, they don't bite ;-)

Configuration

Next, you 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.

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.

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 the list of acquaintances 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.

Sending messages to people

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

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

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.

Running goofey in the same 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.

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!)

To use the cftp and chttp apt methods:

First make sure that the cftp and chttp files have been installed in /usr/lib/apt/methods/. The easiest way of doing this if you're using Debian is to install the Debian package of circle.

[At the time of writing, no binary .deb's of circle are being distributed from the web page, though the source does come with a debian/ subdirectory, so you can create your own with something like `fakeroot ./debian/rules binary'.]

Then, change all occurrences of `ftp://' in your /etc/apt/sources.list file to `cftp://', and similarly change 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.