[tor-commits] [flashproxy/master] move some documentation around for a more coherent structure
infinity0 at torproject.org
infinity0 at torproject.org
Thu Nov 21 13:18:46 UTC 2013
commit 1ab29f3a4aa4c9243ab82931f778a0e9d7ce9c85
Author: Ximin Luo <infinity0 at gmx.com>
Date: Mon Nov 4 21:07:38 2013 +0000
move some documentation around for a more coherent structure
- separate HTTP-rendezvous-specific info out of facilitator-howto.txt
- move technical design info away from the top-level README
- make it clear the need to distribute your public key
---
facilitator/INSTALL | 13 ++-------
facilitator/Makefile.am | 2 +-
facilitator/README | 45 ++++++++----------------------
facilitator/doc/facilitator-design.txt | 32 ++++++++++++++++++++++
facilitator/doc/facilitator-howto.txt | 47 ++++----------------------------
facilitator/doc/gmail-howto.txt | 14 ++++++++--
facilitator/doc/http-howto.txt | 43 +++++++++++++++++++++++++++++
7 files changed, 106 insertions(+), 90 deletions(-)
diff --git a/facilitator/INSTALL b/facilitator/INSTALL
index 345d74a..5a89f6f 100644
--- a/facilitator/INSTALL
+++ b/facilitator/INSTALL
@@ -14,17 +14,8 @@ facilitator-reg-daemon, facilitator-reg, and fac.py to /usr/local/bin.
It also installs System V init files to /etc/init.d/.
The pre/post-install scripts create a user for the daemon to as, and
-sets up the initscripts in the default system runlevels.
-
-They also generate a RSA key in /usr/local/etc/flashproxy/reg-daemon.{key,pub}.
-You should securely distribute the public key to anyone that wants to
-use your facilitator; they will need to pass it as the
---facilitator-pubkey option to flashproxy-reg-email.
-
-You should also edit /usr/local/etc/default/facilitator-email-poller to
-contain your Gmail address and /usr/local/etc/flashproxy/reg-email.pass
-to contain your app-specific password; see doc/gmail-howto.txt for
-instructions.
+sets up the initscripts in the default system runlevels. They also
+generate a RSA key in /usr/local/etc/flashproxy/reg-daemon.{key,pub}.
Uninstall.
diff --git a/facilitator/Makefile.am b/facilitator/Makefile.am
index 6a3cdfc..6252596 100644
--- a/facilitator/Makefile.am
+++ b/facilitator/Makefile.am
@@ -19,7 +19,7 @@ initscript_SCRIPTS = init.d/facilitator init.d/facilitator-email-poller init.d/f
dist_initconf_DATA = default/facilitator default/facilitator-email-poller default/facilitator-reg-daemon
endif
-dist_doc_DATA = doc/appengine-howto.txt doc/facilitator-howto.txt doc/gmail-howto.txt README
+dist_doc_DATA = doc/appengine-howto.txt doc/facilitator-design.txt doc/facilitator-howto.txt doc/gmail-howto.txt doc/http-howto.txt README
dist_example_DATA = examples/fp-facilitator examples/reg-email.pass
dist_appengine_DATA = appengine/app.yaml appengine/config.go appengine/fp-reg.go appengine/README
appengineconf_DATA = appengine/config.go
diff --git a/facilitator/README b/facilitator/README
index 49f17ce..f994977 100644
--- a/facilitator/README
+++ b/facilitator/README
@@ -6,40 +6,17 @@ For instructions on building/installing this package from source, see
INSTALL. (This should only be necessary if your distro does not already
integrate this package into its repositories.)
-For instructions on setting up and running the facilitator, see
-doc/facilitator-howto.txt.
-
-== Overview
-
-The facilitator consists of a backend server that is essentially a
-dynamic database of client addresses, as well as helper programs that
-receive client registrations from the Internet over various means and
-pass them to the backend. There are three supported helper rendezvous
-methods: HTTP, URL, and email.
-
-The HTTP rendezvous uses an HTTP server and a CGI program. The HTTP
-server is responsible for speaking TLS and invoking the CGI program. The
-CGI program receives client registrations and proxy requests for
-clients, parses them, and forwards them to the backend. We use Apache 2
-as the HTTP server. The CGI script is facilitator.cgi. The backend is
-facilitator.
+Each installation has its own public-private keypair, typically in
+reg-daemon.{pub,key} in your flashproxy config directory. You will need
+to securely distribute the public part (.pub) to your users - e.g. by
+publishing it somewhere, signed by your own PGP key.
-The email rendezvous uses the helper program facilitator-email-poller.
-Clients use the flashproxy-reg-email program to send an encrypted
-message to a Gmail address. The poller constantly checks for new
-messages and forwards them to facilitator-reg.
+There are three supported helper rendezvous methods: HTTP, URL, and
+email. Each helper method may require additional manual configuration;
+see the corresponding doc/x-howto.txt for more details.
-facilitator-reg is a simple program that forwards its standard input to
-a locally running facilitator-reg-daemon process.
-
-facilitator-reg-daemon accepts connections containing encrypted client
-registrations and forwards them to the facilitator. It exists as a
-process of its own so that only one program requires access to the
-facilitator's private key.
-
-The URL rendezvous uses the helper program flashproxy-reg-email. The
-helper program doesn't actually make a registration; rather, it prints
-out a URL which, when retrieved, makes the registration.
+For suggestions on configuring a dedicated facilitator machine, see
+doc/facilitator-howto.txt.
-fac.py is a Python module containing code common to the various
-facilitator programs.
+For documentation on the design of the facilitator components, see
+doc/facilitator-design.txt.
diff --git a/facilitator/doc/facilitator-design.txt b/facilitator/doc/facilitator-design.txt
new file mode 100644
index 0000000..f26acc2
--- /dev/null
+++ b/facilitator/doc/facilitator-design.txt
@@ -0,0 +1,32 @@
+The main facilitator program is a backend server that is essentially a
+dynamic database of client addresses, as well as helper programs that
+receive client registrations from the Internet over various means and
+pass them to the backend. There are three supported helper rendezvous
+methods: HTTP, URL, and email.
+
+facilitator-reg is a simple program that forwards its standard input to
+a locally running facilitator-reg-daemon process.
+
+facilitator-reg-daemon accepts connections containing encrypted client
+registrations and forwards them to the facilitator. It exists as a
+process of its own so that only one program requires access to the
+facilitator's private key.
+
+The HTTP rendezvous uses an HTTP server and a CGI program. The HTTP
+server is responsible for speaking TLS and invoking the CGI program. The
+CGI program receives client registrations and proxy requests for
+clients, parses them, and forwards them to the backend. We use Apache 2
+as the HTTP server. The CGI script is facilitator.cgi. The backend is
+facilitator.
+
+The email rendezvous uses the helper program facilitator-email-poller.
+Clients use the flashproxy-reg-email program to send an encrypted
+message to a Gmail address. The poller constantly checks for new
+messages and forwards them to facilitator-reg.
+
+The URL rendezvous uses the helper program flashproxy-reg-email. The
+helper program doesn't actually make a registration; rather, it prints
+out a URL which, when retrieved, makes the registration.
+
+fac.py is a Python module containing code common to the various
+facilitator programs.
diff --git a/facilitator/doc/facilitator-howto.txt b/facilitator/doc/facilitator-howto.txt
index 7cd2f78..6f71772 100644
--- a/facilitator/doc/facilitator-howto.txt
+++ b/facilitator/doc/facilitator-howto.txt
@@ -1,4 +1,8 @@
-This document describes how to configure a flash proxy facilitator on Debian 7.
+This document describes how to configure a server running the facilitator on
+Debian 7. It is not necessary to make things work, but gives you some added
+security, and is a good reference if you want to create a dedicated VM for a
+facilitator from scratch.
+
We will use the domain name fp-facilitator.example.com.
== Basic and security setup
@@ -49,44 +53,3 @@ Restart servers.
# /etc/init.d/ssh restart
# /etc/init.d/shorewall start
# /etc/init.d/shorewall6 start
-
-== HTTP server setup
-
-Apache is the web server that runs the CGI program.
-
- # apt-get install apache2 libapache2-mod-evasive
- # a2enmod ssl headers
-
-Edit /etc/apache2/ports.conf and comment out the port 80 configuration.
-
- # NameVirtualHost *:80
- # Listen 80
-
-Edit examples/fp-facilitator as per the instructions given in that file, and
-install it to /etc/apache2/sites-available/fp-facilitator or whatever is
-appropriate for your apache2 installation.
-
-Link the configured site into sites-enabled.
- # a2ensite fp-facilitator
-
-=== HTTPS setup
-
-The HTTP server should serve only over HTTPS and not unencrypted HTTP.
-You will need a certificate and private key from a certificate
-authority. An article on making a certificate signing request and
-getting it signed is here:
- http://www.debian-administration.org/articles/284
-This is the basic command to generate a CSR.
- $ openssl req -new -nodes -out fp-facilitator.csr.pem
-The instructions below assume you have an offline private key
-in fp-facilitator.key.pem and a certificate in fp-facilitator.crt.pem.
-
-Make a file containing both the private key and a certificate.
-
- $ cat fp-facilitator.key.pem fp-facilitator.crt.pem > fp-facilitator.pem
- $ chmod 400 fp-facilitator.pem
-
-Copy the new fp-facilitator.pem to the facilitator server as
-/etc/apache2/fp-facilitator.pem.
-
- # /etc/init.d/apache2 restart
diff --git a/facilitator/doc/gmail-howto.txt b/facilitator/doc/gmail-howto.txt
index f7c0598..426d52c 100644
--- a/facilitator/doc/gmail-howto.txt
+++ b/facilitator/doc/gmail-howto.txt
@@ -1,6 +1,16 @@
These are instructions for setting up a Gmail account for use with the
-email-based rendezvous and flashproxy-reg-email. These instructions were
-current as of May 2013.
+email-based rendezvous (facilitator-email-poller / flashproxy-reg-email).
+
+You are strongly advised to use a new Google account dedicated for this
+purpose. For those that need to protect their information even from
+Google, we provide some instructions on how to do this below.
+
+Once you have an email address and the password for it, you should add
+this information to reg-email.pass in your flashproxy config directory.
+
+== Creating a Google account securely
+
+These instructions were current as of May 2013.
You may have trouble if you are using Tor to create the account, for two
reasons. The first is that exit nodes are a source of abuse and Google
diff --git a/facilitator/doc/http-howto.txt b/facilitator/doc/http-howto.txt
new file mode 100644
index 0000000..99ebf9b
--- /dev/null
+++ b/facilitator/doc/http-howto.txt
@@ -0,0 +1,43 @@
+These are instructions for how to set up an Apache Web Server for handling
+the HTTP registration method (facilitator.cgi / flashproxy-reg-http).
+
+== HTTP server setup
+
+Apache is the web server that runs the CGI program.
+
+ # apt-get install apache2 libapache2-mod-evasive
+ # a2enmod ssl headers
+
+Edit /etc/apache2/ports.conf and comment out the port 80 configuration.
+
+ # NameVirtualHost *:80
+ # Listen 80
+
+Edit examples/fp-facilitator as per the instructions given in that file, and
+install it to /etc/apache2/sites-available/fp-facilitator or whatever is
+appropriate for your apache2 installation.
+
+Link the configured site into sites-enabled.
+ # a2ensite fp-facilitator
+
+=== HTTPS setup
+
+The HTTP server should serve only over HTTPS and not unencrypted HTTP.
+You will need a certificate and private key from a certificate
+authority. An article on making a certificate signing request and
+getting it signed is here:
+ http://www.debian-administration.org/articles/284
+This is the basic command to generate a CSR.
+ $ openssl req -new -nodes -out fp-facilitator.csr.pem
+The instructions below assume you have an offline private key
+in fp-facilitator.key.pem and a certificate in fp-facilitator.crt.pem.
+
+Make a file containing both the private key and a certificate.
+
+ $ cat fp-facilitator.key.pem fp-facilitator.crt.pem > fp-facilitator.pem
+ $ chmod 400 fp-facilitator.pem
+
+Copy the new fp-facilitator.pem to the facilitator server as
+/etc/apache2/fp-facilitator.pem.
+
+ # /etc/init.d/apache2 restart
More information about the tor-commits
mailing list