Format_C/pivilion
1
0
Fork 0
mirror of https://gitlab.com/hacklab01/pivilion.git synced 2025-04-29 16:47:17 +00:00
Code Issues Projects Releases Wiki Activity

Update pivilion manual setup

v3d 2024-06-08 17:16:29 +00:00
parent 3da48a131d
commit 522cafc983
1 changed files with 458 additions and 458 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

916
pivilion-manual-setup.md

@ -1,459 +1,459 @@
# Pivilion Manual Setup
https://gitlab.com/hacklab01/pivilion/-/wikis/pivilion-manual-setup/
[[_TOC_]]
## 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, 4 or Zero W / 2 hardware and is built on top of Raspbberry Pi OS GNU/Linux. It has Apache 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. 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 systems for publishing media on the web.
## About This Manual
This manual shows how to install Pivilion on your Raspberry Pi from scratch and use it as a portable darknet or local network gallery. It installs Tor with Apache as a hidden service and offers scripts to help facilitate the download and installation of web publication tools.
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
1. Micro USB power adapter (check RPi requirements, but ideally 2.5A or 3A for Pi4) - a cable is also fine (you can connect to any USB port)
1. Min 8 GB (micro)SD card
1. SD card reader (and a microSD to SD adapter if necessary)
1. Ethernet cable (or proper wpa_supplicant.conf to connect to WiFi with Pi Zero - generate one on [wifi.pivilion.net](https://wifi.pivilion.net/))
1. HDMI cable - for connection to a screen - 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 Legacy image](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy) - the "lite" image is recomkended 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. We are using the Legacy image while we iron out some problems with captive portal mode.
1. [Tor Browser](https://www.torproject.org/download/download-easy.html.en) - used only for checking if the gallery works on Tor (not for generating galleries)
1. A network scanning tool like [Nmap](https://nmap.org/) 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!**
1. [Putty SSH client](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - Windows only
1. [Filezilla sFTP client](https://filezilla-project.org/) - 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, the Advanced Package Tool. 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 (Raspbnerry Pi OS is based on Debian).
### Installing Raspbperry Pi OS
Always get a current Raspbperry Pi OS Legacy image before installing Pivilion. It will drastically speed up the update / upgrade step of the manual. Use the official [Raspberry Pi documentation gettig started guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-images-on-chrome-os) to learn how to handle images on your OS.
### 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 Linux, Windows or Mac. 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", use a network discovery tool to find it's IP address, or check your router administrator intarface for the ip assigned to your Pi.
#### Using WiFi Only to Connect to the Pi
If a physical network connection is unavailable or you're using the Raspberry Pi Zero W / 2 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 some countries. 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](https://nmap.org/) 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 to [Lazy mode](#lazy-mode).
### Upgrading the System
`sudo apt update && sudo apt upgrade -y`
### Installing Apache
Apache is a free and open-source cross-platform web server software, released under the terms of Apache License 2.0. Apache is developed and maintained by an open community of developers under the auspices of the Apache Software Foundation.
`sudo apt install apache2 -y`
You can now navigate to your RPi's IP (or hostname - raspberry) using a browser.
You will see Apache's placeholder page.
### Installing PHP
`sudo apt install php -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.
Apt will install all required dependencies.
### 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](#configuring-tor) 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 Apache'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 [use scallion on github](https://github.com/lachesis/scallion) to customize it afterwards.)
This should show the same Apache 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.
1. "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.
1. "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.1.1. That means you can connect to it with
`ssh pi@10.1.1.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.**
1. "pikey" is used to setup a WiFi network and password to be used in onion mode.
1. "hotglue" is used to install or restore a hotglue installation
1. "static" is used to convert hotglue into a static website
1. "generator" will enable or disable the pivilion generator on port 81
1. "htaccess" will remove or reset redirection in /var/www/html/pivilion/gen
### Using Hotglue to Setup a website
Hotglue is a unique tool for web publication & samizdat. It has a fun to use interface and is a community project. It also has some security issues and that's why we convert it to static HTML before serving it on the darknet. Websites generated with the generator script all look the same so this si the prefered way to setup a website when not using full custom HTML / javascript. In order to install or revert hotglue.
When using hotglue just add "?edit" to the index.php of your homeapge and log in with the username and password you setup. When done use the command `static` to convert the page into static HTML. If you'd like to edit again, use `hotglue` to restore (or reinstall) Hotglue.
### Using the Generator Script to Setup a website
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. [Media type and format guide: image, audio, and video content on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats) has a nice 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. [FFmpeg Wiki FFmpeg and VP9 Encoding Guide](hhttps://trac.ffmpeg.org/wiki/Encode/VP9) is a good 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 want to change file size limits, you can edit the php.ini file with
`sudo nano /etc/php/7.3/apache2/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 Apache with
`sudo service apache2 force-reload`
### Server Directory Breakdown
The Pivilion Apache configuration keeps all its files in
```
/var/www/html/pivilion/
|-- gen --> data that apache serves to clients (website goes here)
| `--- .htaccess --> redirect definitions for captive
|-- gen.php --> generator script main PHP file
|-- images --> generator scirpt images
|-- index.html --> HTML layout for generator script
|-- scripts --> scripts for generator script
`-- skeleton --> files that are copied into galleries generated by the generator script
```
### .htaccess File Breakdown
When running in hotspot mode the system makes use of redirect rules that are quire important because all requests need to be redirected in order for client machines to register the captive portal and open it in the browser. There rules are set by the .htaccess file in the /var/www/html/pivilion/gen directory (the server directory). The rules set here are for allowing access to Hotglue and Generator Script files (queries to all other files will be redirected to http://10.1.1.1/index.php).
**When uploading custom HTML and using hotspot mode adjusting this file file accordingly is required** (it will not work otherwise)
Allowing access to a file:
`RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$`
This allows access to the file "pi_logo_128.png" in the directory the .htaccess file resides in.
Allowing access to a directory:
`RewriteCond %{REQUEST_URI} !(\/img\/.*)$`
This allows access to the directory "img" in the directory the .htaccess file resides in (and any / all files inside it).
Default .htaccess for reference:
```
RewriteEngine on
RewriteCond %{REQUEST_URI} !(\/index\.php)$
RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
RewriteCond %{REQUEST_URI} !(\/content\/.*)$
RewriteCond %{REQUEST_URI} !(\/index\.php)$
RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
RewriteCond %{REQUEST_URI} !(\/content\/.*)$
RewriteCond %{REQUEST_URI} !(\/css\/.*)$
RewriteCond %{REQUEST_URI} !(\/doc\/.*)$
RewriteCond %{REQUEST_URI} !(\/docker\/.*)$
RewriteCond %{REQUEST_URI} !(\/img\/.*)$
RewriteCond %{REQUEST_URI} !(\/js\/.*)$
RewriteCond %{REQUEST_URI} !(\/modules\/.*)$
RewriteCond %{REQUEST_URI} !(\/tests\/.*)$
RewriteCond %{REQUEST_URI} !(\/upload\/.*)$
RewriteCond %{REQUEST_URI} !(\/*.php)$
RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]
```
The last line
`RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]`
should always be kept!
### 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](https://filezilla-project.org/) 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 Apache's config in /etc/apache2/ 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](https://filezilla-project.org/) 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 contents 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.
### Tips'n'tricks
Pivilion changes constantly and it's being developed by basically two people. We do our best to test stuff but it will often break. With the addition of captive portal mode and Hotglue, stuff got a bit complicated and configurations from different modes may "leak" and cause havoc.
A couple of helpful tips:
- if networking doesn't seem to work reset it to with `onion` - it will disable hotspot captive portal redirection and allow you to access your Pi via your local network after reboot
- use `htaccess` to remove or reset redirection if the .htaccess file stays behind in onion mode (it should only be there in hotspot mode).
- if hotglue fails to install you can also back it up and restore it manually by copying everything to and from /var/www/html/pivilion/gen with an SFTP client like Filezilla
- all the configuration files are located in /home/pi/piviilion/config/ - the scripts copy everything from there
- the scripts are in /usr/local/bin/, feel free to open and change them or use only the parts you need to get your desired configuration working
- if you can't write in the home dir or in /var/www/ fix persmissions with `sudo chown -R pi:pi /home/pi; sudo chown -R www-data:www-data /var/www/; sudo chmod -R 775 /var/www;`
- feel free to ask questions in
### 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.
### 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 apache2 php hostapd dnsmasq git tor zip -y; 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; onion; 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
# Pivilion Manual Setup
https://gitlab.com/hacklab01/pivilion/-/wikis/pivilion-manual-setup/
[[_TOC_]]
## 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, 4 or Zero W / 2 hardware and is built on top of Raspbberry Pi OS GNU/Linux. It has Apache 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. 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 systems for publishing media on the web.
## About This Manual
This manual shows how to install Pivilion on your Raspberry Pi from scratch and use it as a portable darknet or local network gallery. It installs Tor with Apache as a hidden service and offers scripts to help facilitate the download and installation of web publication tools.
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
1. Micro USB power adapter (check RPi requirements, but ideally 2.5A or 3A for Pi4) - a cable is also fine (you can connect to any USB port)
1. Min 8 GB (micro)SD card
1. SD card reader (and a microSD to SD adapter if necessary)
1. Ethernet cable (or proper wpa_supplicant.conf to connect to WiFi with Pi Zero - generate one on [wifi.pivilion.net](https://wifi.pivilion.net/))
1. HDMI cable - for connection to a screen - 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 Legacy image](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy) - the "lite" image is recommended for Pivilion - 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. We are using the Legacy image while we iron out some problems with captive portal mode.
1. [Tor Browser](https://www.torproject.org/download/download-easy.html.en) - used only for checking if the gallery works on Tor (not for generating galleries)
1. A network scanning tool like [Nmap](https://nmap.org/) 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!**
1. [Putty SSH client](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - Windows only
1. [Filezilla sFTP client](https://filezilla-project.org/) - 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, the Advanced Package Tool. 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 (Raspbnerry Pi OS is based on Debian).
### Installing Raspbperry Pi OS
Always get a current Raspbperry Pi OS Legacy image before installing Pivilion. It will drastically speed up the update / upgrade step of the manual. Use the official [Raspberry Pi documentation gettig started guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-images-on-chrome-os) to learn how to handle images on your OS.
### 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 Linux, Windows or Mac. 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", use a network discovery tool to find it's IP address, or check your router administrator intarface for the ip assigned to your Pi.
#### Using WiFi Only to Connect to the Pi
If a physical network connection is unavailable or you're using the Raspberry Pi Zero W / 2 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 some countries. 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](https://nmap.org/) 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 to [Lazy mode](#lazy-mode).
### Upgrading the System
`sudo apt update && sudo apt upgrade -y`
### Installing Apache
Apache is a free and open-source cross-platform web server software, released under the terms of Apache License 2.0. Apache is developed and maintained by an open community of developers under the auspices of the Apache Software Foundation.
`sudo apt install apache2 -y`
You can now navigate to your RPi's IP (or hostname - raspberry) using a browser.
You will see Apache's placeholder page.
### Installing PHP
`sudo apt install php -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.
Apt will install all required dependencies.
### 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](#configuring-tor) 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 Apache'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 [use scallion on github](https://github.com/lachesis/scallion) to customize it afterwards.)
This should show the same Apache 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.
1. "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.
1. "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.1.1. That means you can connect to it with
`ssh pi@10.1.1.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.**
1. "pikey" is used to setup a WiFi network and password to be used in onion mode.
1. "hotglue" is used to install or restore a hotglue installation
1. "static" is used to convert hotglue into a static website
1. "generator" will enable or disable the pivilion generator on port 81
1. "htaccess" will remove or reset redirection in /var/www/html/pivilion/gen
### Using Hotglue to Setup a website
Hotglue is a unique tool for web publication & samizdat. It has a fun to use interface and is a community project. It also has some security issues and that's why we convert it to static HTML before serving it on the darknet. Websites generated with the generator script all look the same so this si the prefered way to setup a website when not using full custom HTML / javascript. In order to install or revert hotglue.
When using hotglue just add "?edit" to the index.php of your homeapge and log in with the username and password you setup. When done use the command `static` to convert the page into static HTML. If you'd like to edit again, use `hotglue` to restore (or reinstall) Hotglue.
### Using the Generator Script to Setup a website
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. [Media type and format guide: image, audio, and video content on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats) has a nice 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. [FFmpeg Wiki FFmpeg and VP9 Encoding Guide](hhttps://trac.ffmpeg.org/wiki/Encode/VP9) is a good 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 want to change file size limits, you can edit the php.ini file with
`sudo nano /etc/php/7.3/apache2/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 Apache with
`sudo service apache2 force-reload`
### Server Directory Breakdown
The Pivilion Apache configuration keeps all its files in
```
/var/www/html/pivilion/
|-- gen --> data that apache serves to clients (website goes here)
| `--- .htaccess --> redirect definitions for captive
|-- gen.php --> generator script main PHP file
|-- images --> generator scirpt images
|-- index.html --> HTML layout for generator script
|-- scripts --> scripts for generator script
`-- skeleton --> files that are copied into galleries generated by the generator script
```
### .htaccess File Breakdown
When running in hotspot mode the system makes use of redirect rules that are quire important because all requests need to be redirected in order for client machines to register the captive portal and open it in the browser. There rules are set by the .htaccess file in the /var/www/html/pivilion/gen directory (the server directory). The rules set here are for allowing access to Hotglue and Generator Script files (queries to all other files will be redirected to http://10.1.1.1/index.php).
**When uploading custom HTML and using hotspot mode adjusting this file file accordingly is required** (it will not work otherwise)
Allowing access to a file:
`RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$`
This allows access to the file "pi_logo_128.png" in the directory the .htaccess file resides in.
Allowing access to a directory:
`RewriteCond %{REQUEST_URI} !(\/img\/.*)$`
This allows access to the directory "img" in the directory the .htaccess file resides in (and any / all files inside it).
Default .htaccess for reference:
```
RewriteEngine on
RewriteCond %{REQUEST_URI} !(\/index\.php)$
RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
RewriteCond %{REQUEST_URI} !(\/content\/.*)$
RewriteCond %{REQUEST_URI} !(\/index\.php)$
RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
RewriteCond %{REQUEST_URI} !(\/content\/.*)$
RewriteCond %{REQUEST_URI} !(\/css\/.*)$
RewriteCond %{REQUEST_URI} !(\/doc\/.*)$
RewriteCond %{REQUEST_URI} !(\/docker\/.*)$
RewriteCond %{REQUEST_URI} !(\/img\/.*)$
RewriteCond %{REQUEST_URI} !(\/js\/.*)$
RewriteCond %{REQUEST_URI} !(\/modules\/.*)$
RewriteCond %{REQUEST_URI} !(\/tests\/.*)$
RewriteCond %{REQUEST_URI} !(\/upload\/.*)$
RewriteCond %{REQUEST_URI} !(\/*.php)$
RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]
```
The last line
`RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]`
should always be kept!
### 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](https://filezilla-project.org/) 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 Apache's config in /etc/apache2/ 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](https://filezilla-project.org/) 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 contents 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.
### Tips'n'tricks
Pivilion changes constantly and it's being developed by basically two people. We do our best to test stuff but it will often break. With the addition of captive portal mode and Hotglue, stuff got a bit complicated and configurations from different modes may "leak" and cause havoc.
A couple of helpful tips:
- if networking doesn't seem to work reset it to with `onion` - it will disable hotspot captive portal redirection and allow you to access your Pi via your local network after reboot
- use `htaccess` to remove or reset redirection if the .htaccess file stays behind in onion mode (it should only be there in hotspot mode).
- if hotglue fails to install you can also back it up and restore it manually by copying everything to and from /var/www/html/pivilion/gen with an SFTP client like Filezilla
- all the configuration files are located in /home/pi/piviilion/config/ - the scripts copy everything from there
- the scripts are in /usr/local/bin/, feel free to open and change them or use only the parts you need to get your desired configuration working
- if you can't write in the home dir or in /var/www/ fix persmissions with `sudo chown -R pi:pi /home/pi; sudo chown -R www-data:www-data /var/www/; sudo chmod -R 775 /var/www;`
- feel free to ask questions in
### 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.
### 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 apache2 php hostapd dnsmasq git tor zip -y; 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; onion; 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! :)