Setting up a community server

The latest version of the community server is 0.7.1pre.

Overview

Community servers help OneSwarm users manage their friends, and they can make adding and removing friends completely automatic. Anyone can run a community server, and this page describes how to configure our reference implementation. The latest version (0.7.0pre) also supports file publishing, wherein community server members can advertise files to all other members through a website.

The community server binary and source are available here.

Each client's interaction with a community server is a three step process:

1. During its first connection, the client registers its public key with the server. By default, community servers accept registrations from arbitrary users, although the number of registrations is limited per-IP address.
2. Next, the server verifies the client's identity by issuing a challenge and verifying the client's signed response
3. Finally, the server computes a list of keys nearby the client (as determined by hashing the client's public key) and returns these.

Security

Community servers can be run in two modes:

1. Open community servers accept client registrations from anyone. This is the default configuration.
2. Authenticated community servers require clients to present a valid username/password via HTTP authentication for every server request.

To avoid man-in-the-middle attacks on friend feeds, we recommend using HTTPS/SSL, although this is not required. Setting up an SSL-enabled community server is described below.

In general, the community server has not been extensively tested and may contain security bugs and/or vulnerabilities. You shouldn't run it unless you understand and accept the potential risks.

HOWTO: Set up an open community server with SSL

Create certificate

First, you'll need to generate an SSL certificate to verify your server. An easy way to do this is to simply use Java's keytool:

keytool -keystore keystore -alias community  -keyalg RSA -dname "cn=community.oneswarm.org" -genkey

Note: You'll need to replace community.oneswarm.org with the hostname of your server. You'll be prompted to pick a password during the key generation. Keep this handy, you'll need it when configuring the community server.

Note2: On windows keytool.exe is not on the path by default, run C:\Program Files\Java\jre\bin\keytool.exe instead

Copy certificate file

keytool generate a file called keystore, copy this file to community server folder.

The remaining steps will be more thoroughly documented here soon, but after generating the certificate, you'll need to:

1. Installing MySQL
2. Modifying the sample-communtiy.conf (to include your database info, as well as your SSL certificate if you are using SSL)
3. (Potentially) changing the JAVA_HOME variable in the start-* script for your platform
4. Running the start script with your configuration file as an argument

HOWTO: Private servers

A private community server is accessible only by users with accounts and where accounts can be created only by administrators.

Assuming you've already got MySQL and the server working in its default configuration, you'll want to change several settings in your community.conf file.

• require.auth.for.key.registration -- set to true, will require users who subscribe to provide a username / pw to receive a set of friends from your server
• allow.signup -- set to false, will disable account creation by anyone except an administrator
• signup.requires.captcha -- set to false (since only administrators can create accounts, presumably spam won't be a problem)
• require.swarm.moderation -- you might want to set this to false if all users are trusted. This will show swarms on the webpage immediately, without requiring moderation.

Next, you'll need to add an additional security constraint to the web.xml file located at: war/WEB-INF/web.xml. The default constraint is provided in the file as an example, and you can simply uncomment it.

<security-constraint>
	<display-name>Private server constraint</display-name>
	<web-resource-collection>
		<web-resource-name>All JSP pages, previews, downloads, rss</web-resource-name>
		<url-pattern>*.jsp</url-pattern>
		<url-pattern>/dl</url-pattern>
		<url-pattern>/preview</url-pattern>
		<url-pattern>/details</url-pattern>
		<url-pattern>/rss</url-pattern>
	</web-resource-collection>
	<auth-constraint>
		<role-name>admin</role-name>
		<role-name>moderator</role-name>
		<role-name>user</role-name>
	</auth-constraint>
	<user-data-constraint>
		<transport-guarantee>NONE</transport-guarantee>
	</user-data-constraint>
</security-constraint>

Finally, you'll need to change the welcome-page from files.jsp to logon.jsp. Replace:

<welcome-file-list>
  <welcome-file>files.jsp</welcome-file>
</welcome-file-list>

with

<welcome-file-list>
  <welcome-file>logon.jsp</welcome-file>
</welcome-file-list>

You can add additional constraints if you like using this (and the admin / signup request) as models. Now, if you reload any page, you should be immediately redirected to the login page.