Using Onionspray¶

This guide goes beyond the quick start setup laid out in the tutorial.

Creating a project¶

As explained in the building blocks section, Onionspray sites are configured through projects.

A project can be created in three ways:

Using the ./onionspray create command, as explained in the tutorial.
Using a template file ending in .tconf, when the Onion Service keys still need to be generated.
Using a configuration file ending in .conf, when the Onion Service keys already exists.

All three ways ends up generating a .conf file, which can later be edited and used to reconfigure a project.

Which way to use depends on what are your needs. When unsure, start with the create command detailed in the tutorial. The rest of this section will focus on the template (.tconf) approach.

Regarding the Onion Service keys, there are two ways to proceed:

With automatically-generated addresses.
With manually-mined (or pre-existing) addresses.

With automatically-generated Onions Service addresses¶

Random addresses¶

Random addresses are created with the %NEW_V3_ONION% placeholder in project templates.

Create a config file with a .tconf suffix -- we'll pretend it's foo.tconf -- and use this kind of syntax:

set project myproject
hardmap %NEW_V3_ONION% foo.com
hardmap %NEW_V3_ONION% foo.co.uk
hardmap %NEW_V3_ONION% foo.de

... and then run

./onionspray config foo.tconf

... which will create the onions for you and will populate a foo.conf for you, and it will then configure Onionspray from that. You should probably delete foo.tconf afterwards, since forcibly reusing it would trash your existing onions.

Vanity addresses¶

Vanity addresses are created with the %NEW_V3_VANITY_ONION_% placeholder in project templates. The syntax is slightly different from the %NEW_V3_ONION% because %NEW_V3_VANITY_ONION_% requires an argument specifying the initial text prefix for the generated .onion address.

Create a config file with a .tconf suffix -- we'll pretend it's foo.tconf -- and use this kind of syntax:

set project myproject
hardmap %NEW_V3_VANITY_ONION_foo% foo.com
hardmap %NEW_V3_VANITY_ONION_bar% foo.co.uk
hardmap %NEW_V3_VANITY_ONION_baz% foo.de

... and then run

./onionspray config foo.tconf

... which will create the onions for you and will populate a foo.conf for you, and it will then configure Onionspray from that. You should probably delete foo.tconf afterwards, since forcibly reusing it would trash your existing onions.

Note that the generated .onion for foo.com will begin with foo, since the %NEW_V3_VANITY_ONION_foo% placeholder was used; similarly, the .onion for foo.co.uk and foo.de will begin, respectively, with bar and baz.

With manually-mined Onion Service addresses¶

Generating the key¶

Random addresses¶

A random .onion address can be manually generated with onionspray genkey:

Run onionspray genkey -- it will print the name of the onion it generates.
Run it as many times as you wish/need.

Vanity addresses¶

Vanity addresses can be manually generated in a number of ways:

With onionspray genkey-vanity <filter>:
- Run onionspray genkey-vanity <filter> -- it will print the name of the onion it generates.
- Run it as many times as you wish/need.
- Example onionspray genkey-vanity test -- it will generate an address beginning with test.
- This uses Onionmine under the hood.
Alternately get a tool like mkp224o, Onionmine, oniongen-go, or oniongen-rs and use that to "mine" a desirable .onion address:
- mkp224o:
  - Written in C.
  - For CPUs.
  - Requires a UNIX-like platform, like Linux, *BSD, or Cygwin.
- Onionmine:
  - A wrapper around mkp224o.
  - Also aids the process of getting CA-signed TLS certificates.
- oniongen-go:
  - Written in Go.
  - For CPUs.
  - Works on Linux and Windows, uses regex.
- oniongen-rs:
  - Written in Rust.
  - For CPUs.
  - Works similarly to oniongen-go, but is written in Rust.
- Be sure to store your mined keys in secrets.d, naming the keys like someverylongonionaddressinvolvingalotofbase23characterss.v3pub.key and someverylongonionaddressinvolvingalotofbase32characterss.v3sec.key

Check also the mining tips.

Creating the config file¶

Create a config file with a .conf suffix - we'll pretend it's foo.conf - and use this kind of syntax, substituting a2s3c4d5e6f7g8h9 for the onion address that you generated.

set project myproject hardmap z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd foo.com

... and then (IMPORTANT) run:

./onionspray config foo.conf

... which will configure Onionspray.

Starting a project¶

Like this:

./onionspray start myproject

Subdomains management¶

Overview¶

Subdomains are supported like this, for dev as an example:

set project myproject
hardmap z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd foo.com dev

... and if you have multiple subdomains:

hardmap z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd foo.com dev blogs dev.blogs [...]

How it works¶

When you are setting up the mappings in a config file, you may have to accommodate "subdomains"; the general form of a internet hostname is like this:

hostname.domain.tld # like: www.facebook.com or www.gov.uk
or: hostname.domain.sld.tld # like: www.amazon.co.uk
hostname.subdom.domain.tld # like: www.prod.facebook.com
hostname.subsubdom.subdom.domain.tld # cdn.lhr.eu.foo.net
hostname.subsubsubdom.subsubdom.subdom.domain.tld # ...

... and so on, where:

tld = top level domain
sld = second level domain
domain = generally the name of the organisation you are interested in
subdomain = some kind of internal structure
hostname = actual computer, or equivalent

When you are setting up mappings, generally the rules are:

you will map one domain per onion
you will ignore all hostnames
you will append all possible subdomain stems

So if your browser tells you that you are fetching content from cdn7.dublin.ireland.europe.foo.co.jp, you should add a line like:

hardmap %NEW_V3_ONION% foo.co.jp europe ireland.europe dublin.ireland.europe

... and Onionspray should do the rest. All this is necessary purely for correctness of the self-signed SSL-Certificates - which are going to be weird, anyway - and the rest of the HTML-rewriting code in Onionspray will be blind to subdomains.

Managing lots of sites and subdomains¶

Example:

www.foo.com.au
www.syd.foo.com.au
www.per.foo.com.au,
www.cdn.foo.net
www.foo.aws.amazon.com
...

Put them all in the same project as separate mappings, remembering to avoid the actual "hostnames" as described above:

set project fooproj
hardmap %NEW_V3_ONION% foo.com.au syd per
hardmap %NEW_V3_ONION% foo.net cdn
hardmap %NEW_V3_ONION% foo.aws.amazon.com

Onion mapping/translations will be applied for all sites in the same project.

System startup and housekeeping procedures¶

Once you have installed Onionspray and configured and tested it for your project, run:

./onionspray make-scripts

This will create two files:

./onionspray-init.sh: for installing on your system as a startup script
./onionspray-housekeeping.sh: for cronjob log rotation and other cleanup work

Please read the individual files for installation instructions; local setup is intended to be pretty simple.