Skip to content

Using Onionspray

Creating a project

Okay, there are two ways to create your own project:

  1. With automatically-generated addresses.
  2. With manually-mined addresses.

With automatically-generated Onions Service addresses

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%
hardmap %NEW_V3_ONION%
hardmap %NEW_V3_ONION%

... 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.

With manually-mined Onion Service addresses

  • Do onionspray genkey - it will print the name of the onion it generates
  • Do this as many times as you wish/need.
  • Alternately get a tool like scallion, shallot, or eschalot and use that to "mine" a desirable onion address.
    • - in C, for CPUs
    • Seems okay on Linux, not sure about other platforms
    • - in C#, for CPUs & GPUs (GPU == very fast)
    • Advertised as working on Windows, Linux; works well on OSX under "Mono"
    • - in C, for CPUs
    • Works well under Linux, and BSD systems. Uses multiple threads. Can use a wordlist to generate onion addresses
    • Be sure to store your mined private keys in secrets with a filename like z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd.v3pub.key for the public key and z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd.v3sec.key for the secret key, where z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd is the corresponding onion address.
  • 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

... and then (IMPORTANT) run:

./onionspray config foo.conf

... which will configure Onionspray.

Starting a project

Like this:

./onionspray start myproject

Subdomains management


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

set project myproject
hardmap z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd dev

... and if you have multiple subdomains:

hardmap z2walkyky3zzv52g3gedrhxa665qdrslyvrljg5wppibx34olslnxgqd dev blogs dev.blogs [...]

How it works

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

  • hostname.domain.tld # like: or
  • or: hostname.domain.sld.tld # like:
  • hostname.subdom.domain.tld # like:
  • hostname.subsubdom.subdom.domain.tld #
  • 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, you should add a line like:

hardmap %NEW_V3_ONION% 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


  • ...

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% syd per
hardmap %NEW_V3_ONION% cdn
hardmap %NEW_V3_ONION%

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:

  • ./ for installing on your system as a startup script
  • ./ for cronjob log rotation and other cleanup work

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