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 withtest
. - This uses Onionmine under the hood.
- Run
-
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 likesomeverylongonionaddressinvolvingalotofbase23characterss.v3pub.key
andsomeverylongonionaddressinvolvingalotofbase32characterss.v3sec.key
- mkp224o:
Check also the mining tips.
Creating the config file¶
-
Create a config file with a
.conf
suffix - we'll pretend it'sfoo.conf
- and use this kind of syntax, substitutinga2s3c4d5e6f7g8h9
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.comhostname.subsubdom.subdom.domain.tld
# cdn.lhr.eu.foo.nethostname.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.