|
|
= Guidelines for developing services to be run on Tor machines =
|
|
|
# Guidelines for developing services to be run on Tor machines
|
|
|
|
|
|
The Tor Project develops a couple of services designed to be run on Tor machines. This page is a collection of guidelines for developing such services. The rule of thumb is that every service that runs a custom process on a Tor machine should adhere to these guidelines.
|
|
|
|
|
|
Services that only provide static web content are in general not affected by these guidelines, even if they depend on certain tools to be built. That also means that if a service ''can'' be built so that it doesn't require dynamic processes by only serving static content, that makes deployment on Tor machines a lot easier.
|
|
|
Services that only provide static web content are in general not affected by these guidelines, even if they depend on certain tools to be built. That also means that if a service _can_ be built so that it doesn't require dynamic processes by only serving static content, that makes deployment on Tor machines a lot easier.
|
|
|
|
|
|
== Dependencies ==
|
|
|
## Dependencies
|
|
|
|
|
|
The following guidelines apply to dependencies on other software packages, either developed by The Tor Project or by third parties:
|
|
|
|
... | ... | @@ -14,34 +14,36 @@ The following guidelines apply to dependencies on other software packages, eithe |
|
|
|
|
|
The following table contains most if not all services running on Tor machines that have at least one dependency (again, excluding services providing static web content, which only depend on Apache):
|
|
|
|
|
|
||= '''Service''' =||= '''Repository''' =||= '''Maintainers''' =||= '''Debian stable packages (good)''' =||= '''Debian backports packages (okay)''' =||= '''Self-provided libraries (bad)''' =||= '''Packages installed via third-party package managers (really bad)''' =||
|
|
|
|||||||||||||| '' '''Python-based services''' '' ||
|
|
|
|| [https://bridges.torproject.org/ bridges.torproject.org] || [https://gitweb.torproject.org/bridgedb.git bridgedb] || isis, sysrqb || python2.7 python-dev build-essential libgpgme11 libgpgme11-dev openssl libgeoip-dev sqlite3 geoip-database python-setuptools python-twisted-core python-twisted-web python-twisted-mail python-twisted-names python-gpgme python-recaptcha python-mako python-beautifulsoup python-babel python-ipaddr python-openssl python-crypto || || pygeoip, BridgeDB installed via git || None. Make certain to to erase everything from `/home/bridgedb/bridgedb/requirements.txt` before running `/srv/bridges.torproject.org/bin/deploy` to ensure that Pip is not used. ||
|
|
|
||[https://compass.torproject.org/ compass.torproject.org] || [https://gitweb.torproject.org/compass.git compass] ||gsathya || python-flask, python-jinja2, python-werkzeug || || || ||
|
|
|
|| [https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-consensus-health consensus-health list] || [https://gitweb.torproject.org/doctor.git doctor] || atagar || || || [https://stem.torproject.org/ stem] via git || ||
|
|
|
|| [https://gettor.torproject.org/ gettor.torproject.org] || ? || sukhe || ? || ? || ? || ? ||
|
|
|
|| [https://support.torproject.org/ support.torproject.org] || [https://gitweb.torproject.org/pups.git pups] || phoul, lunar, helix || apache2 prosody libapache2-mod-passenger python2 python-django python-django-south || || [https://code.google.com/p/prosody-modules/wiki/mod_auto_accept_subscriptions mod_auto_accept_subscriptions] via hg || ||
|
|
|
|| [https://torperf.torproject.org/ torperf.torproject.org] || [https://gitweb.torproject.org/torperf.git torperf] || karsten || automake build-essential coreutils git libevent-dev libssl-dev || || [https://gitweb.torproject.org/pytorctl.git TorCtl] via git || ||
|
|
|
|| [https://weather.torproject.org/ weather.torproject.org] || ? || karsten || ? || ? || ? || ? ||
|
|
|
|||||||||||||| '' '''Java-based services''' '' ||
|
|
|
||= '''Service''' =||= '''Repository''' =||= '''Maintainers''' =||= '''Debian stable packages (good)''' =||= '''Debian backports packages (okay)''' =||= '''Self-provided libraries (bad)''' =||= '''Packages installed via third-party package managers (really bad)''' =||
|
|
|
|| [https://collector.torproject.org/ collector.torproject.org] || [https://gitweb.torproject.org/metrics-db.git metrics-db] || karsten || ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java openjdk-6-jdk || || [https://gitweb.torproject.org/metrics-lib.git metrics-lib] via git submodule || ||
|
|
|
|| [https://consensus-health.torproject.org/ consensus-health.torproject.org] || [https://gitweb.torproject.org/doctor.git/shortlog/refs/heads/java java branch of doctor] ||karsten || ant apache2 git openjdk-6-jdk || || [http://commons.apache.org/proper/commons-codec/ Apache Commons Codec] and [http://commons.apache.org/proper/commons-compress/ Compress] via wget, [https://gitweb.torproject.org/metrics-lib.git metrics-lib] via git submodule || ||
|
|
|
|| [https://exonerator.torproject.org/ exonerator.torproject.org] || [https://gitweb.torproject.org/exonerator.git exonerator] || karsten || ant apache2 git libcommons-codec-java libpostgresql-jdbc-java openjdk-6-jdk postgresql tomcat6 || || || ||
|
|
|
|| [https://metrics.torproject.org/ metrics.torproject.org] || [https://gitweb.torproject.org/metrics-web.git metrics-web] || karsten || ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java libpostgresql-jdbc-java libpq-dev libservlet3.0-java openjdk-6-jdk postgresql r-base-dev tomcat6 || || [https://gitweb.torproject.org/metrics-lib.git metrics-lib] via git submodule || [http://cran.r-project.org/web/packages/Rserve/index.html Rserve], [http://cran.r-project.org/web/packages/ggplot2/index.html ggplot2], and [http://cran.r-project.org/web/packages/RPostgreSQL/index.html RPostgreSQL] via CRAN ||
|
|
|
|| [https://onionoo.torproject.org/ onionoo.torproject.org] || [https://gitweb.torproject.org/onionoo.git onionoo] || karsten || ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java libgoogle-gson-java libservlet3.0-java openjdk-6-jdk tomcat6 || || [https://gitweb.torproject.org/metrics-lib.git metrics-lib] via git submodule || ||
|
|
|
|||||||||||||| '' '''Go-based services''' '' ||
|
|
|
||= '''Service''' =||= '''Repository''' =||= '''Maintainers''' =||= '''Debian stable packages (good)''' =||= '''Debian backports packages (okay)''' =||= '''Self-provided libraries (bad)''' =||= '''Packages installed via third-party package managers (really bad)''' =||
|
|
|
|| [https://check.torproject.org/ check.torproject.org] || [https://gitweb.torproject.org/check.git check] || arlolra || git golang gettext python-dateutil python-stem || || || [https://github.com/samuel/go-gettext go-gettext] via `go get` ||
|
|
|
|||||||||||||| '' '''Haskell-based services''' '' ||
|
|
|
||= '''Service''' =||= '''Repository''' =||= '''Maintainers''' =||= '''Debian stable packages (good)''' =||= '''Debian backports packages (okay)''' =||= '''Self-provided libraries (bad)''' =||= '''Packages installed via third-party package managers (really bad)''' =||
|
|
|
|| TorDNSEL || [https://gitweb.torproject.org/tordnsel.git TorDNSEL] || arlolra || git ghc libghc-hunit-dev libghc-binary-dev libghc-conduit-dev libghc-conduit-extra-dev libghc-mtl-dev libghc-network-dev libghc-stm-dev || || || ||
|
|
|
|
|
|
== Permissions ==
|
|
|
|= **Service** =|= **Repository** =|= **Maintainers** =|= **Debian stable packages (good)** =|= **Debian backports packages (okay)** =|= **Self-provided libraries (bad)** =|= **Packages installed via third-party package managers (really bad)** =|
|
|
|
|---------------|------------------|-------------------|-------------------------------------|----------------------------------------|-------------------------------------|------------------------------------------------------------------------|
|
|
|
||||||| _ **Python-based services** _ |
|
|
|
| [bridges.torproject.org](https://bridges.torproject.org/) | [bridgedb](https://gitweb.torproject.org/bridgedb.git) | isis, sysrqb | python2.7 python-dev build-essential libgpgme11 libgpgme11-dev openssl libgeoip-dev sqlite3 geoip-database python-setuptools python-twisted-core python-twisted-web python-twisted-mail python-twisted-names python-gpgme python-recaptcha python-mako python-beautifulsoup python-babel python-ipaddr python-openssl python-crypto | | pygeoip, BridgeDB installed via git | None. Make certain to to erase everything from `/home/bridgedb/bridgedb/requirements.txt` before running `/srv/bridges.torproject.org/bin/deploy` to ensure that Pip is not used. |
|
|
|
|[compass.torproject.org](https://compass.torproject.org/) | [compass](https://gitweb.torproject.org/compass.git) |gsathya | python-flask, python-jinja2, python-werkzeug | | | |
|
|
|
| [consensus-health list](https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-consensus-health) | [doctor](https://gitweb.torproject.org/doctor.git) | atagar | | | [stem](https://stem.torproject.org/) via git | |
|
|
|
| [gettor.torproject.org](https://gettor.torproject.org/) | ? | sukhe | ? | ? | ? | ? |
|
|
|
| [support.torproject.org](https://support.torproject.org/) | [pups](https://gitweb.torproject.org/pups.git) | phoul, lunar, helix | apache2 prosody libapache2-mod-passenger python2 python-django python-django-south | | [mod_auto_accept_subscriptions](https://code.google.com/p/prosody-modules/wiki/mod_auto_accept_subscriptions) via hg | |
|
|
|
|| [torperf.torproject.org](https://torperf.torproject.org/) || [torperf](https://gitweb.torproject.org/torperf.git) || karsten || automake build-essential coreutils git libevent-dev libssl-dev || || [TorCtl](https://gitweb.torproject.org/pytorctl.git) via git || ||
|
|
|
| [weather.torproject.org](https://weather.torproject.org/) | ? | karsten | ? | ? | ? | ? |
|
|
|
|-----------------------------------------------------------|---|---------|---|---|---|---|
|
|
|
||||||| _ **Java-based services** _ |
|
|
|
|= **Service** =|= **Repository** =|= **Maintainers** =|= **Debian stable packages (good)** =|= **Debian backports packages (okay)** =|= **Self-provided libraries (bad)** =|= **Packages installed via third-party package managers (really bad)** =|
|
|
|
| [collector.torproject.org](https://collector.torproject.org/) | [metrics-db](https://gitweb.torproject.org/metrics-db.git) | karsten | ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java openjdk-6-jdk | | [metrics-lib](https://gitweb.torproject.org/metrics-lib.git) via git submodule | |
|
|
|
| [consensus-health.torproject.org](https://consensus-health.torproject.org/) | [java branch of doctor](https://gitweb.torproject.org/doctor.git/shortlog/refs/heads/java) |karsten | ant apache2 git openjdk-6-jdk | | [Apache Commons Codec](http://commons.apache.org/proper/commons-codec/) and [Compress](http://commons.apache.org/proper/commons-compress/) via wget, [metrics-lib](https://gitweb.torproject.org/metrics-lib.git) via git submodule | |
|
|
|
| [exonerator.torproject.org](https://exonerator.torproject.org/) | [exonerator](https://gitweb.torproject.org/exonerator.git) | karsten | ant apache2 git libcommons-codec-java libpostgresql-jdbc-java openjdk-6-jdk postgresql tomcat6 | | | |
|
|
|
| [metrics.torproject.org](https://metrics.torproject.org/) | [metrics-web](https://gitweb.torproject.org/metrics-web.git) | karsten | ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java libpostgresql-jdbc-java libpq-dev libservlet3.0-java openjdk-6-jdk postgresql r-base-dev tomcat6 | | [metrics-lib](https://gitweb.torproject.org/metrics-lib.git) via git submodule | [Rserve](http://cran.r-project.org/web/packages/Rserve/index.html), [ggplot2](http://cran.r-project.org/web/packages/ggplot2/index.html), and [RPostgreSQL](http://cran.r-project.org/web/packages/RPostgreSQL/index.html) via CRAN |
|
|
|
| [onionoo.torproject.org](https://onionoo.torproject.org/) | [onionoo](https://gitweb.torproject.org/onionoo.git) | karsten | ant-optional ant apache2 git junit4 libcommons-codec-java libcommons-compress-java libcommons-lang-java libgoogle-gson-java libservlet3.0-java openjdk-6-jdk tomcat6 | | [metrics-lib](https://gitweb.torproject.org/metrics-lib.git) via git submodule | |
|
|
|
||||||| _ **Go-based services** _ |
|
|
|
|= **Service** =|= **Repository** =|= **Maintainers** =|= **Debian stable packages (good)** =|= **Debian backports packages (okay)** =|= **Self-provided libraries (bad)** =|= **Packages installed via third-party package managers (really bad)** =|
|
|
|
| [check.torproject.org](https://check.torproject.org/) | [check](https://gitweb.torproject.org/check.git) | arlolra | git golang gettext python-dateutil python-stem | | | [go-gettext](https://github.com/samuel/go-gettext) via `go get` |
|
|
|
||||||| _ **Haskell-based services** _ |
|
|
|
|= **Service** =|= **Repository** =|= **Maintainers** =|= **Debian stable packages (good)** =|= **Debian backports packages (okay)** =|= **Self-provided libraries (bad)** =|= **Packages installed via third-party package managers (really bad)** =|
|
|
|
| TorDNSEL | [TorDNSEL](https://gitweb.torproject.org/tordnsel.git) | arlolra | git ghc libghc-hunit-dev libghc-binary-dev libghc-conduit-dev libghc-conduit-extra-dev libghc-mtl-dev libghc-network-dev libghc-stm-dev | | | |
|
|
|
|
|
|
## Permissions
|
|
|
|
|
|
A service must not require torproject-admin and/or root access in its normal operation or to update, stop, start, and maintain the service. But of course, setting up a service requires root. That's why the following guidelines are subdivided into a setup and an operation phase.
|
|
|
|
|
|
=== Setup phase ===
|
|
|
### Setup phase
|
|
|
|
|
|
During setup, the following steps can be executed using root privileges, which will be done by the sysadmins, of course:
|
|
|
|
... | ... | @@ -50,7 +52,7 @@ During setup, the following steps can be executed using root privileges, which w |
|
|
- Configure system-provided services like Apache and/or Tomcat, create databases, setup mail, and so on, based on the service's needs. Every deviation from the defaults should be explained to the sysadmins. Changing the defaults may make it harder to update packages.
|
|
|
- If necessary, allow the role account to restart system services like Apache or Tomcat, or read their logs, which is usually restricted to root.
|
|
|
|
|
|
=== Operation phase ===
|
|
|
### Operation phase
|
|
|
|
|
|
As stated above, a service must not require torproject-admin and/or root access in its normal operation or to update, stop, start, and maintain the service. The following operations are permitted for the service role account:
|
|
|
|
... | ... | |