2017-02-01 08:19:33 +00:00
|
|
|
# The Enterprise Onion Toolkit
|
2017-02-01 08:38:03 +00:00
|
|
|
## eotk (c) 2017 Alec Muffett
|
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
# Status - ALPHA
|
2017-02-01 11:56:52 +00:00
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
The EOTK goal is to provide a tool for prototyping, and deploying at
|
|
|
|
scale, HTTP and HTTPS onion sites to provide official presence for
|
|
|
|
popular websites.
|
2017-02-01 11:39:26 +00:00
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
The results are essentially a "man in the middle" proxy; set them up
|
|
|
|
only for your own sites or for sites which do not require login
|
|
|
|
credentials of any kind.
|
2017-02-01 13:02:24 +00:00
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
The resulting NGINX configs are probably both buggy and not terribly
|
|
|
|
well tuned; please consider this project to be very much "early days",
|
|
|
|
but I shall try not to modify the configuration file format.
|
2017-02-01 11:59:52 +00:00
|
|
|
|
2017-02-01 12:01:29 +00:00
|
|
|
The `softmap` support is untested, and needs some more work to make it
|
|
|
|
nice to launch and integrate with OnionBalance; please avoid it for
|
|
|
|
the moment.
|
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
## Usage Notes
|
2017-02-01 11:39:26 +00:00
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
When connecting to the resulting onions over HTTP/SSL, you will be
|
|
|
|
using wildcard self-signed SSL certificates - you *will* encounter
|
|
|
|
many "broken links" which are due to the SSL certificate not being
|
|
|
|
valid. This is *expected* and *proper* behaviour.
|
2017-02-01 11:39:26 +00:00
|
|
|
|
2017-02-04 10:49:03 +00:00
|
|
|
To help cope with this, for any domain (eg:
|
|
|
|
www.foofoofoofoofoof.onion) the EOTK provides a fixed url:
|
2017-02-01 11:39:26 +00:00
|
|
|
|
|
|
|
* `https://www.foofoofoofoofoof.onion/hello-onion/`
|
|
|
|
|
2017-02-04 10:49:47 +00:00
|
|
|
...which (`/hello-onion/`) is internally served by the NGINX proxy and
|
|
|
|
provides a stable, fixed URL for SSL certificate acceptance; inside
|
|
|
|
TorBrowser another effective solution is to open all the broken links,
|
|
|
|
images and resources "in a new Tab" and accept the certificate there.
|
2017-02-01 11:39:26 +00:00
|
|
|
|
|
|
|
In production, of course, one would expect to use an SSL EV
|
2017-02-04 10:49:03 +00:00
|
|
|
certificate to provide identity and assurance to an onion site,
|
|
|
|
rendering these issues moot.
|
2017-02-01 11:39:26 +00:00
|
|
|
|
|
|
|
# Requirements
|
|
|
|
|
2017-02-04 18:06:09 +00:00
|
|
|
* `tor` (latest stable)
|
|
|
|
* `nginx` (latest stable) with the following features & modules
|
|
|
|
* `headers_more`
|
|
|
|
* `ngx_http_substitutions_filter_module`
|
|
|
|
* `http_sub`
|
|
|
|
* `http_ssl`
|
|
|
|
|
|
|
|
On Linux, scripts are provided to compile these.
|
|
|
|
|
|
|
|
On OSX, these are available via Homebrew.
|
2017-02-01 11:39:26 +00:00
|
|
|
|
2017-02-04 10:58:52 +00:00
|
|
|
# User Manual
|
|
|
|
|
|
|
|
Intuitively obvious to the most casual observer:
|
2017-02-04 10:49:03 +00:00
|
|
|
|
|
|
|
* `eotk config [filename]` # default `onions.conf`
|
2017-02-04 12:51:47 +00:00
|
|
|
* *synonyms:* `conf`, `configure`
|
2017-02-04 12:57:02 +00:00
|
|
|
* parses the config file and sets up and populates the projects
|
2017-02-04 12:51:47 +00:00
|
|
|
* `eotk status projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* process status
|
2017-02-04 12:51:47 +00:00
|
|
|
* `eotk maps projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* print which onions correspond to which dns domains
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk start projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* start projects
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk stop projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* stop projects
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk bounce projectname ...` # or: `-a` for all
|
2017-02-04 12:51:47 +00:00
|
|
|
* *synonyms:* `restart`, `reload`
|
2017-02-04 12:57:02 +00:00
|
|
|
* stop, and restart, projects
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk debugon projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* enable verbose tor logs
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk debugoff projectname ...` # or: `-a` for all
|
2017-02-04 12:57:02 +00:00
|
|
|
* disable verbose tor logs
|
2017-02-04 10:49:03 +00:00
|
|
|
* `eotk harvest projectname ...` # or: `-a` for all
|
2017-02-04 12:51:47 +00:00
|
|
|
* *synonyms:* `onions`
|
2017-02-04 12:57:02 +00:00
|
|
|
* print list of onions used by projects
|
2017-02-04 16:36:17 +00:00
|
|
|
* `eotk ps`
|
|
|
|
* do a stupid grep for possibly orphaned processes
|
2017-02-04 10:49:03 +00:00
|
|
|
|
2017-02-01 11:39:26 +00:00
|
|
|
# Installation: OSX
|
|
|
|
|
|
|
|
Currently works on OSX with Homebrew:
|
|
|
|
|
|
|
|
* install homebrew - http://brew.sh/
|
|
|
|
* `git clone https://github.com/alecmuffett/eotk.git`
|
|
|
|
* `cd eotk`
|
|
|
|
* `sh ./000-setup-osx.sh` # installs required software; if you're worried, check it first
|
|
|
|
|
2017-02-04 16:41:12 +00:00
|
|
|
# Installation: Raspbian
|
|
|
|
|
2017-02-04 18:20:45 +00:00
|
|
|
* `git clone https://github.com/alecmuffett/eotk.git`
|
|
|
|
* `cd eotk`
|
|
|
|
* Read [000-setup-raspbian.md](000-setup-raspbian.md) and follow the instructions.
|
2017-02-04 16:41:12 +00:00
|
|
|
|
|
|
|
# Installation: Debian/Ubuntu
|
2017-02-01 11:39:26 +00:00
|
|
|
|
|
|
|
Work in progress. Feedback welcome.
|
2017-02-01 13:02:24 +00:00
|
|
|
|
2017-02-04 10:58:52 +00:00
|
|
|
# I want to experiment!
|
|
|
|
|
|
|
|
If you want to experiment with some prefabricated projects, try this:
|
|
|
|
|
|
|
|
* `sh ./001-configure-demo.sh` # creates a working config file, `demo.conf`
|
|
|
|
* `eotk config demo.conf` # creates tor & nginx config files; lists onion sites
|
|
|
|
* `eotk start default`
|
|
|
|
* Now you can...
|
|
|
|
* Connect to one of the onions cited on screen for the `default` project
|
|
|
|
* Play SSL-Certificate-Acceptance-Whackamole
|
|
|
|
* Browse a little...
|
|
|
|
* `eotk stop default`
|
2017-02-04 10:49:03 +00:00
|
|
|
|
2017-02-01 13:02:24 +00:00
|
|
|
# I want to create a new project / my own configuration!
|
|
|
|
|
|
|
|
You can either add a new project to the demo config file, or you can
|
2017-02-04 10:58:52 +00:00
|
|
|
create a new config for yourself. If you want an onion for `foo.com`,
|
|
|
|
the simplest configuration file probably looks like this:
|
2017-02-01 13:02:24 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
set project myproject
|
|
|
|
hardmap secrets.d/xxxxxxxxxxxxxxxx.key foo.com
|
|
|
|
```
|
|
|
|
|
2017-02-04 10:06:42 +00:00
|
|
|
...and if you create a file called `project.conf` containing those
|
2017-02-01 13:09:53 +00:00
|
|
|
lines, then you should be able to do:
|
2017-02-01 13:02:24 +00:00
|
|
|
|
|
|
|
```
|
2017-02-04 10:58:52 +00:00
|
|
|
eotk configure project.conf
|
|
|
|
eotk start myproject
|
2017-02-01 13:02:24 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## But how do I create my own "secrets.d/xxxxxxxxxxxxxxxx.key"?
|
|
|
|
|
|
|
|
```
|
|
|
|
cd secrets.d
|
|
|
|
./generate-onion-key.sh
|
|
|
|
```
|
|
|
|
|
2017-02-04 18:28:37 +00:00
|
|
|
* Do this as many times as you wish/need.
|
|
|
|
* Alternately get a tool like `scallion` or `shallot` and use that to
|
|
|
|
"mine" a desirable onion address.
|
|
|
|
* Be sure to store the private key in `secrets.d` with a filename like
|
|
|
|
`xxxxxxxxxxxxxxxx.key` where `xxxxxxxxxxxxxxxx` is the corresponding
|
|
|
|
onion address.
|
2017-02-04 18:16:56 +00:00
|
|
|
|
2017-02-04 18:17:35 +00:00
|
|
|
## But I not only have `www.foo.com`, I have `www.dev.foo.com`!
|
2017-02-04 18:16:56 +00:00
|
|
|
|
|
|
|
Subdomains are supported thusly:
|
|
|
|
|
|
|
|
```
|
|
|
|
set project myproject
|
|
|
|
hardmap secrets.d/xxxxxxxxxxxxxxxx.key foo.com dev
|
|
|
|
```
|
|
|
|
|
|
|
|
...and if you have multiple subdomains:
|
|
|
|
|
|
|
|
```
|
|
|
|
hardmap secrets.d/xxxxxxxxxxxxxxxx.key foo.com dev blogs dev.blogs [...]
|
|
|
|
```
|