Skip to content

GitLab

GitLab's annual major release is around the corner. Along with a lot of new and exciting features, there will be a few breaking changes. Learn more here.

Last edited by v3d
Page history

pivilion manual setup

Pivilion Manual Setup

About Pivilion

Pivilion is a decentralized, uncensored, user-curated web gallery operating system and gallery management software running on nodes hosted by the general public and distributed through clearnet and Tor. The aim of the gallery-host project is to create a nomadic free virtual environment that connects art-oriented users (both creators and consumers) by offering a participatory model of interaction. The base methodology of achieving this is allowing less experienced and community-driven users-curators to actively approach free network technologies while utilizing all the upsides of net tech, promoting connectibility, privacy and maximum freedom of curating content. (While the advanced users are welcome to re-create their own virtual Pi-based galleries.) By removing the gallery sites from the blogs and domains to a physical gadget of the Pi - Pivilion engages & connects users on two levels of interaction - virtual and physical, ideological and technical. The interaction with Pivilion could further concepts of freedom, education and spark collaborative potentials of one’s communities.

It runs on top of Raspberry Pi 1, 2, 3 or Zero hardware and is built on top of Raspbberry Pi OS GNU/Linux. It has Lighty server and Tor networking built in and uses the Tor network to host exhibitions out of the box. The entire system and documentation is available for download on a central website, hosted both on clearnet and on the Tor network and distributed as SD card images available for free download. The website serves as both a central point for deployment of the system and for the announcement of global exhibitions running on nodes. It is designed so that the user-curator can use any network (even public networks behind firewalls) to host an exhibition. Each Pivilion device receives a Tor onion domain automatically the first time it’s activated. The system provides the user with backend access to a system for publishing images, videos or websites within a gallery. The gallery runs on a CMS designed specially for hosting online gallery events, with features such as different rooms, complete with Mozilla’s Togetherjs integrated into each seperate room.

About This Manual

This manual shows how 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. It's recommended to read through the entire manual, before attempting to install it on a Raspberry Pi.

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.

What You Will Need

Hardware

  1. Raspberry Pi
  2. Micro USB power adapter (check RPi requirements, but ideally 2.5A) - a cable is also fine (you can connect to any USB port)
  3. Min 8 GB (micro)SD card
  4. SD card reader (and a microSD to SD adapter if necessary)
  5. Ethernet cable
  6. HDMI cable - optional

You can connect the RPi to a HDMI screen (with 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.

Software

  1. Raspberry Pi OS image - the "lite" image is reccomended for Pivlion - note that this version doesn't have a graphical user interface installed - you can only use the terminal interface if you connect the Pi to a screen with a HDMI cable
  2. Tor Browser - used only for checking if the gallery works on Tor (not for generating galleries)
  3. A network scanning tool like Nmap or Fing (avaliable for iOS and Android) Be careful with network scanning software - scanning networks that are not yours may be illegal in your country!
  4. Putty SSH client - Windows only
  5. Filezilla sFTP client - optional, for backing up and uploading files to the Pi

Software Installation

Pivilion runs on top of libre / free software which is avaliable in the Raspbberry Pi OS repositories. To download and install software we will use APT. Advanced Package Tool, or APT, is a free-software user interface that works with core libraries to handle the installation and removal of software on Debian, Ubuntu, and related Linux distributions.

Installing Raspbperry Pi OS

Always get a current Raspbperry Pi OS 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 the Pi

Once that’s done, connect your RPi to a DHCP network 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.

Using WiFi Only to Connect to the Pi

If a physical network connection is unavailable or you're using the Raspberry Pi Zero W that uses wireless networking only, you need to generate a wpa_supplicant.conf file and use a card reader to place the file in the root of the FAT32 formatted boot partition of your RPi SD card. You can do this manually or generate a conf file with a generator at the following URL. https://wifi.pivilion.net/

wpa_supplicant is a free software implementation of an IEEE 802.11i supplicant for Linux, FreeBSD, NetBSD, QNX, AROS, Microsoft Windows, Solaris, OS/2 (including eComStation) and Haiku. In addition to being a fully featured WPA2 supplicant, it also implements WPA and older wireless LAN security protocols.

The config file generated will assume you're using WPA2 security on your network. If not, you will have to modify it manually according to your network settings.

It also adds a country code to your WiFi settings which Raspbperry Pi OS made mandatory for the RPi 3b+ and it has been known to cause issues for some people. In the generated config file the country will be set to Bolivia which will allow you to push your WiFi to higher power then legally allowed in your country. If you feel uneasy about this please change this to your country code. Note that your Pi won't automatically transmit at a higher rate without being instructed to do so, but that's outside the scope of this document.

Finding the Pi's IP

There are several options for finding the IP of your device:

  1. Logging into your local router and checking the list of connected devices
  2. Using a network scanning tool like Nmap or Fing (avaliable for iOS and Android)
  3. Connecting it to a display with a HDMI cable and just reading the IP from the screen. If you installed Raspbperry Pi OS lite it will just write the IP address before prompting you to login. If you installed the full Raspbperry Pi OS version with a GUI you can find your IP in the upper right corner by hovering over the networking icon

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.

Enter 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

ssh pi@10.0.0.5

(Replace 10.0.0.5 with your RPi's IP)

Changing the Default Password

It's really important to change the default password for obvious security reasons. Change it with

passwd

and input the new password.

Expanding the Filesystem

This is optional depending on the Raspbperry Pi OS version you are using.

Check used and available storage with

df -h

And use raspi-config to expand the filesystem if needed (i.e. if its size differs a lot from the SD card capacity).

sudo raspi-config (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). :).

If so, skip here.

Upgrading the System

sudo apt update && sudo apt upgrade -y

Installing Lighttpd

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.

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

Enabling 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

Installing Hostapd

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!

Installing Dnsmasq

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.

Installing Git

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.

Installing Tor

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 Raspbperry Pi OS, so you will have to become root using by issuing

sudo -s

Pulling Config and Settings from GiLtab

cd / (DO NOT SKIP THIS STEP)

git init

git remote add origin https://gitlab.com/hacklab01/pivilion.git

git fetch origin

git checkout -f --track origin/master

Fixing Some Permission issues

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.

sudo reboot

ssh pi@your.Pi.IP

Run pivilion to copy some extra files to their proper positions!

pivilion

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!

Post Installation Options

Configuring Tor

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, #)

RunAsDeamon 1

In the section intended for hidden services only, uncomment (by removing the # in front of) the two lines

*HiddenServiceDir /var/lib/tor/hidden_service

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!

Command Overview

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.

  1. "pivilion" will display some info and a brief tutorial. It will also copy some files to proper positions.
  2. "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.
  3. "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 ssh pi@10.1.0.1 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.
  4. "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.

Changing PHP file size limits

If you need to upload larger files, or more files at once, you can edit the file /etc/php/7.3/cgi/php.ini with

sudo nano /etc/php/7.3/cgi/php.ini

There you will find options such as

post_max_size upload_max_filesize max_file_uploads

You can observe their values and read the comments around them to figure out what they do and what inputs they take. After it's adjusted you need to restart Lighty with

sudo service lighttpd force-reload

Custom HTML

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.

Backing Up HTML Content

Since Pivlion is a server, we can use an sFTP client like Filezilla to access it and download and upload files. It uses the same username and password and the same IP that is used for SSH.

In the Filezilla connection boxes

Host: your Pi's IP (the one used for SSH) Username: pi Password: your password (default: raspberry) Port: 22

The remote filesystem will open in the right pane, and your local directories / folders will be in the left. You can drag and drop or right click and upload or download files and directories to and from your Pi.

To back up your gallery navigate to /var/www/html/pivilion/gen in the right pane side and download the contects of the entire directory to a local directory on the left hand side.

To restore a backup, simply upload fromt he local directory to the same remote directory, overwriting its contents.

Upgrading the Pivilion Installation

Since there's a lot of bugs to fix, we fix them often. :)

To upgrade use

sudo -s

cd /

git reset --hard origin/master

git fetch --all

This will delete everything in your gallery and reset to default.

Please make sure to back up!

Alternative Installation Methods

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

Lazy Mode

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.

sudo apt update; sudo apt upgrade -y; sudo apt install lighttpd php-cgi hostapd dnsmasq git tor -y; sudo lighty-enable-mod fastcgi; sudo lighty-enable-mod fastcgi-php; sudo service lighttpd force-reload; cd /; sudo git init; sudo git remote add origin https://gitlab.com/hacklab01/pivilion.git; sudo git fetch origin; sudo git checkout -f --track origin/master; sudo chown -R pi:pi /home/pi; sudo chown -R www-data:www-data /var/www/; sudo chmod -R 775 /var/www; sudo usermod -a -G www-data pi; sudo reboot

The system will reboot automatically and all you need to do is run

pivilion

after that to set up some final stuff and you should be good to go! :)

Please note that Pivilion is in public beta and is sure to have some errors. Don't hesitate to help development by raising issues here https://gitlab.com/hacklab01/pivilion/issues

Now go make some darknet of things galleries! :)