commit 4759de43ed1c9b3c6e1865e5c57e9b3aae84234f Author: iwakeh iwakeh@torproject.org Date: Tue Aug 9 11:51:36 2016 +0200

The install and operating manual (task-18734). --- INSTALL.md | 57 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 21 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md index 0ae4f9a..e941759 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -15,47 +15,62 @@ In the following we'll assume that the host runs Debian stable as operating system, but it should work on any other Linux or possibly even *BSD. Though you'll be mostly on your own with those.

+As Java is available on a variety of other operating systems, these might +work, too. But again you'll be on your own.

Prepare the system ------------------

-Create a working directory for CollecTor. In this guide, we'll assume -that you're using `/srv/collector.torproject.org/` as working directory, -but feel free to use another directory that better suits your needs. +CollecTor is provided by The Tor Project and can be found here: + https://dist.torproject.org/collector/ +Download the tar.gz file with the version number listed in build.xml. +The README inside the tar.gz file has all the information about CollecTor +and explains how to verify the downloaded files.

-$ sudo mkdir -p /srv/collector.torproject.org/ +You need a Java installation. On Debian you can just run:

-Install a few packages: +$ sudo apt-get openjdk-7-jdk

-$ sudo apt-get ant junit4 libasm4-java libcommons-codec-java \ - libcommons-compress-java libcommons-lang3-java libgoogle-gson-java \ - liblogback-java liboro-java libslf4j-java libxz-java openjdk-7-jdk +Configure the relay descriptor downloader +-----------------------------------------

+Run +$ java -DLOGBASE=/path/to/logs -jar collector-<version>.jar +once in order to obtain a configuration properties file.

-Compile CollecTor ------------------ +There are quite a few options to set in collector.properties and the comments +explain their meaning. So, you can set the options to the values you want.

-$ ant compile +Create the paths you set in collector.properties.

+Example: run the relay descriptor downloader +--------------------------------------------

-Configure the relay descriptor downloader ------------------------------------------ +This is a small example about how CollecTor is used. All the other +settings are explained in the default collector.properties.

-Run -$ java -DLOGBASE=/path/to/logs -jar collector-<version>.jar releaydescs -once in order to obtain a configuration properties file. +For running the relay descriptor downloader:

Edit collector.properties and set at least the following value to true:

DownloadRelayDescriptors = true

- -Run the relay descriptor downloader ------------------------------------ - -$ java -DLOGBASE=/path/to/logs -jar collector-<version>.jar relaydescs +$ java -DLOGBASE=/path/to/logs -jar collector-<version>.jar </place/of/collector.properties>

Watch out for INFO-level logs in the log directory you configured. In particular, the lines following "Statistics on the completeness of written relay descriptors:" are quite important.

+In case of the unforeseen ERROR and WARN level logs should help you troubleshoot +your installation. + +Maintenance +----------- + +CollecTor is designed to keep running and attempts to re-run modules even +when previous runs stopped because of a problem. Thus, it is very important +to watch out for WARNING level and especially ERROR level log statements. + +These often will point to problems you can do something about, e.g. a full disk +or missing file system permissions. +