You can choose to download one of our pre-installed images (not available atm) or follow this guide to install Pivilion on your Raspberry Pi from scratch and use it as a portable darknet gallery. It installs Tor with Lighttpd (Lighty) as a hidden service and runs a simple php based gallery system. Tor is free software for enabling anonymous communication and censorship circumvention. However, Pivilion doesn't use Tor for its anonimity features (but Tor still provides them). Tor is used to host a HTTP server as a hidden service. We make extensive use of its NAT punching capabilites to enable us to host a gallery behind NATs and firewalls. Keep in mind that this may or may not break your ISP contract if you do it from home. Using public WiFi to host hidden services, while not technically illegal if you were provided with the password by the owner of the WiFi, may present certain issues with their ISP. Since we're using Tor there is no way for you to get caught. With great power comes great responsibility. Be responsible in what you host and do on the darknet while using Pivilion.
Use a Virtualbox image
For testing Pivilion without a Raspberry Pi, you can use Ubuntu server (or any other Debian-based OS) as a base and install all packages from this manual. Some package names may differ, depending on your system. Use
apt-cache search package name
to search for similar packages.
Run your appliance in bridged networking mode if you need to access your Pivilion appliance from your local network.
You can skip all the Raspberry-specific steps if you chose to use Virtualbox. You can also download prepared Virtualbox appliances with Pivilion completely installed, or a base system to install Pivilion yourself here.
You can also download the complete pre-installed appliance image and run Pivilion in Virtualbox without having to install anything.
What you need
Micro USB power adapter (check RPi requirements, but ideally 2.5A) - a cable is also fine (you can connect to any USB port)
Min 8 GB (micro)SD card
SD card reader (and a microSD to SD adapter if necessary)
HDMI cable - optional
You can connect the RPi to a HDMI screen (plus a USB mouse + keyboard) and connect it to WiFi as you would any computer. However, this setup is meant to be made over SSH - consider your Pi a server (even though it's on a table next to you :)). You can connect it to a display and once you input the WiFi password, just connect to the Pi via SSH from a different computer.
Always get a fresh and current Raspbian image before installing Pivilion. It will drastically speed up the update / upgrade step of the manual. Use this guide from Raspberry Pi's official website. You can use either the full or the lite image, it’s up to you. Choose your system. We’ll be using Linux + dd.
Enabling SSH on your Pi
SSH access is turned off by default for security. We need to do a simple extra step to enable it.
The boot partition on a Pi should be accessible from any machine with an SD card reader, on Windows, Mac, or Linux. If you want to enable SSH, all you need to do is to put a file called ssh in the boot partition. The contents of the file don’t matter: it can contain any text you like, or even nothing at all. When the Pi boots, it looks for this file; if it finds it, it enables SSH and then deletes the file. SSH can still be turned on or off from the Raspberry Pi Configuration application or raspi-config; this is simply an additional way to turn it on if you can’t easily run either of those applications.
Connecting to your Pi
Once that’s done, connect your RPi to a DHCP network with an ethernet cable and power it on. Depending on your network configuration, you can login to your RPi using it's hostname "raspberry", or use a network discovery tool to find it's IP address. Logging into your local router and checking the list of connected devices is also an option.
We will use nmap to scan our DHCP IP range for all hosts that are up. Replace 10.0.0.1/24 with your IP address range. You can also check your router's settings to see all devices connected to your network and their IPs.
nmap 10.0.0.1/24 into your terminal (replace 10.0.0.1 with your network's IP)
Login to your Pi using SSH with username: pi
and password (which will, for security reasons, not be visible as you type it in): raspberry
(Replace 10.0.0.5 with your RPi's IP)
Change the default password
It's really important to change the default password for obvious security reasons. Change it with
and input the new password.
Expand your filesystem
This is optional depending on the Raspbian version you are using.
Check used and available storage with
And use raspi-config to expand the filesystem if needed (i.e. if its size differs a lot from the SD card capacity).
(under Advanced options in the menu find Expand filesystem).
Select finish and reboot.
SSH back into your RPi
Now that you've gained access to your RPi you can continue installing packages (or skip to lazy mode if you really don't care to learn about the components needed to run a hidden service on Tor). :).
Lighttpd (pronounced "lighty") is an open-source web server optimized for speed-critical environments while remaining standards-compliant, secure and flexible.
sudo apt install lighttpd -y
You can now navigate to your RPi's IP (or hostname - raspberry) using a browser.
You will see lighttpd's placeholder page.
Install PHP and modules
sudo apt install php-cgi -y
PHP (Hypertext Preprocessor) is a server-side scripting language designed primarily for (but not limited to) web development. We use it to run our basic gallery generation script.
php-cgi is a PHP to CGI interpreter. CGI (Common Gateway Interface) offers a standard protocol for web servers to interface with executable programs running on a server that generate web pages dynamically. The interpreter is how Lighty handles PHP.
Apt will install all required dependencies.
Enable PHP support in Lighty
Enable the fastcgi module and the php configuration with
sudo lighty-enable-mod fastcgi
sudo lighty-enable-mod fastcgi-php
Reload the lighttpd daemon
sudo service lighttpd force-reload
sudo apt install hostapd -y
Hostapd (Host access point daemon) is a user space software access point capable of turning normal network interface cards into access points and authentication servers. We use it, in conjuction with Dnsmasq, to turn the Rpi into a WiFi access point.
If you pull Pivilion scripts and settings from Gitlab later on, the default SSID will be "Pivilion" and the default WPA2 passphrase will be "darknetofthings".
These can be edited in /etc/hostapd/hostapd.conf. Do this after pulling from git or your config file will get overwritten!
sudo apt install dnsmasq -y
Dnsmasq is a Domain Name System (DNS) forwarder and Dynamic Host Configuration Protocol (DHCP) server for small computer networks. We use it to provide the clients connected to our access point with IP addresses.
sudo apt install git -y
Git (/ɡɪt/) is a version control system (VCS) that is used for software development and other version control tasks. We use it download settings and scripts from our GitLab repository.
sudo apt install tor -y
You can now choose to either pull the Pivilion scripts and Tor / RPi configuration or make the next step manually and make your own custom Tor hidden service.
Cloning Pivilion settings and scripts via Git
We assume that your user is named pi. It will create directories in pi's home dir (/home/pi) and use scripts that reference that directory.
Make sure you are root before doing these steps. The root account is disabled on Raspbian, so you will have to become root using by issuing
Git creates everything as root so we have to fix file permissions in Pi's home directory by issuing
sudo chown -R pi:pi /home/pi
We also need to set the permissions to our www directory so that PHP can write / move files around
sudo chown -R www-data:www-data /var/www/
This command sets Lighty's user "www-data" from the group "www-data" as the owner of /var/www (the webserver root directory)
sudo chmod -R 775 /var/www
This command tells the system that all files and directories in /var/www have the chmod of 775 which means the owner and the group can read write and execute, while everyone else can just read.
sudo usermod -a -G www-data pi
This adds the user pi to the group www-data, so that user can write to the /var/www directory when logged in to SSH or via SFTP.
Now reboot your RPi and log back in.
Run pivilion to copy some extra files to their proper positions!
And follow the brief tutorial.
Editing config files
You should now edit the hostapd config file by issuing
sudo nano /etc/hostapd/hostapd.conf
Change the WiFi SSID (if you like) - the password should definitely be changed!
You can skip this if you cloned everything from GitLab and don't want to make a custom Tor service!
Edit Tor's configuration file /etc/tor/torrc by issuing
sudo nano /etc/tor/torrc
Uncomment (remove the leading hash symbol, #)
In the section intended for hidden services only, uncomment (by removing the # in front of) the two lines
HiddenServicePort 80 127.0.0.1:80*
In order to setup additional services, simply add their ports to this list, followed by your localhost IP (always 127.0.0.1). E.g. for SSH via Tor we would add
HiddenServicePort 22 127.0.0.1:22
Note that hidden service ports don't need to be the same as their local ports. It is recommended to run services on high ports (1024-65535) for (not much) added security. The port for the http service is left at the default port 80, because otherwise we need to input the port in the URL, i.e. 7j4kxhmso6yhz2df.onion:1337 to access the website on port 1337.
Write your changes to the file with Ctrl + O. Exit nano with Ctrl + X.
Now restart tor
sudo systemctl restart tor
Tor will generate a hostname. To view your hostname run
sudo cat /var/lib/tor/hidden_service/hostname
Check if your hidden service works by opening Tor Browser and navigating to your onion domain.
(In case you'd like a vanity .onion address, there is a way to customize it afterwards.)
This should show the same lighttpd placeholder page as before.
That's it - everything should be working now!
If you don't feel like learning about the various components used to build a Tor hidden service, you can just use lazy mode to bundle up individual installations.
All you need to do is paste the following line into your terminal and hit Enter. It will take a couple of minutes to finish.
The system will reboot automatically and all you need to do is run
after that to set up some final stuff and you should be good to go! :)
While logged in to the Pi via SSH there are four commands at your disposal.
All these commands are bash scripts located in the /usr/local/bin directory.
"pivilion" will display some info and a brief tutorial. It will also copy some files to proper positions.
"onion" will set your Pi to start in onion mode on next reboot. This is the default mode. In this mode, the Pi acts as a hidden service on Tor and serves your content.
"hotspot" will set your Pi to start in hotspot mode on next reboot. This mode can be used to connect to the Pi without being connected to a network. The Pi has the IP of 10.1.0.1. That means you can connect to it with
It will also redirect all non-encrypted traffic to this IP, meaning that all traffic will be redirected to your gallery. You can use this mode to serve a local instance of the gallery.
Please remember to set the mode properly before each reboot or you might have to access your Pi via ethernet cable or screen.
"pikey" is used to setup a WiFi network and password to be used in onion mode.
Using the generator script to setup a gallery
After setting everything up, you can find the generator script by entering your Pi's IP address into your browser on port 81. This is only available on your local network, not through Tor - e.g. http://192.168.1.5:81.
The script is very simple - it uses PHP to generate a static HTML site. It can take audio, video and images. The audio and video need to be encoded with certain codecs compatible with HTML5 media reproduction because of patents. Here's a breakdown on what's supported where. You should test and make sure your media files work. The use of WebM, an open, royalty-free media file format is recommended. Here's a VP9 encoding guide for video.
Keep in mind that Tor is slow and optimize your images, audio and video properly!
The gallery generator takes in some basic data such as the name, description, title of the specific works, etc. Sections are vertical while slides are horizontal. Each piece has its own page. You should play around to figure out how it works. Keep in mind that the script will overwrite everything each time you generate a new gallery, so preparing a directory of media and backing up :) is the way to go. This will be better implemented in the future.
You can also choose to overwrite anything the generator script generates or edit it manually just like you would HTML / PHP on any server. Use an FTP client such as Filezilla and the same username / password you would for logging in via SSH (point Filezilla to your Pi's IP and port 22). The directory that's served is /var/www/html/pivilion/gen. You can also edit Lighty's config in /etc/ lighttpd.conf and move the directory to where you see fit.