Web Interface
By default, there is no user authentication for the PiSCSI Web Interface! If you intend to use it on a public network, it is strongly recommended that you enable authentication.
Without authentication, anyone on your local network can do things to your Raspberry Pi like delete data, fill up your drive, reboot, etc.
These instructions assume you've worked through the Setup Instructions and Drive Setup articles. If you have not done so already, visit those pages first, as there are dependencies in this article that rely on those instructions being completed already.
The PiSCSI web interface is written in Python and served up with NGINX Server.
NOTE: This process is not required if you've ran `easyinstall.sh`
1. To install dependencies for the web interface:
sudo apt install nginx-light genisoimage man2html hfsutils dosfstools kpartx unzip unar disktype gettext python3 python3-dev python3-pip python3-venv python3-setuptools python3-wheel libev-dev libevdev2 protobuf-compiler2. Compile the Python protobuf library
This expects that you have checked out the PiSCSI code to ~/piscsi as the pi user.
protoc -I=/home/pi/piscsi/cpp --python_out=/home/pi/piscsi/python/common/src piscsi_interface.proto3. Create the new service
sudo cp -f ~/piscsi/python/web/service-infra/nginx-default.conf /etc/nginx/sites-available/default
sudo cp -f ~/piscsi/python/web/service-infra/502.html /var/www/html/502.html
sudo cp ~/piscsi/python/web/service-infra/piscsi-web.service /etc/systemd/system/piscsi-web.service
sudo systemctl daemon-reload
sudo systemctl enable piscsi-web
sudo systemctl start piscsi-web4. Adjust permissions on the Images Directory
The PiSCSI web interface expects the disk images to be stored in /home/pi/images (or the equivalent home dir of the user that owns the PiSCSI on the system.) That directory should already exist, as it is covered in the Drive Setup document. If you haven't done so already, follow the instructions in the Drive Setup document before proceeding.
For NGINX to have permissions to read and write to /home/pi/images, we will adjust permissions on /home/pi/images and add the www-data account to the pi group. Run the following command to make these changes.
chmod -R 775 /home/pi/images
groups www-data
sudo usermod -a -G pi www-data
groups www-dataAfter running the above, you should see...
pi@raspberrypi:~ $ chmod -R 775 images
pi@raspberrypi:~ $ groups www-data
www-data : www-data
pi@raspberrypi:~ $ sudo usermod -a -G pi www-data
pi@raspberrypi:~ $ groups www-data
www-data : www-data pi5. Create the config dir
The PiSCSI Web Interface stores configuration files in a directly, by default ~/.config/piscsi . You need to create and adjust the permissions on this directory.
mkdir -p ~/.config/piscsi
chmod -R 775 ~/.config/piscsi6. Prepare Mac disk formatting software (optional)
This step is only required if you want to be able to format Mac HFS volumes directly through the Web Interface.
Download the HFS driver archive from https://macintoshgarden.org/sites/macintoshgarden.org/files/apps/mac-hard-disk-drivers.zip and unzip it in ~/piscsi
Download the latest hfdisk release tarball from https://github.com/rdmark/hfdisk/releases and unpack it in a temporary location
cd to the hfdisk directory and run the `make` command, then copy the compiled `hfdisk` binary to /usr/bin
7. The web interface is now ready to use.
If you are not using the piscsi-web service, or have stopped the service, you can launch the Web Interface manually like this:
cd ~/piscsi/python/web
sudo ./start.shUsing the web interface is pretty straight forward. The next steps help you find the IP address of your Raspberry Pi, and provide some screenshots on what it should look like.
1. First we to determine the IP address of the Raspberry Pi using ip addr show. The output of ip addr show will look different depending on your Raspberry Pi model, and if you're using a wired or wireless network connection. In this example we are using a Raspberry Pi Zero W, with a wireless interface but no wired interface. The name of the wireless interface is wlan0, and you are looking for the inet value.
pi@piscsi:~ $ ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
2: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether b8:27:eb:24:ff:c2 brd ff:ff:ff:ff:ff:ff
inet 10.0.0.185/24 brd 10.0.0.255 scope global dynamic noprefixroute wlan0
valid_lft 149455sec preferred_lft 127855sec
inet6 2601:602:8d80:5560::cf50/128 scope global dynamic noprefixroute
valid_lft 581444sec preferred_lft 581444sec
inet6 2601:602:8d80:5560:6c4c:e42:8c89:b7af/64 scope global dynamic mngtmpaddr noprefixroute
valid_lft 299sec preferred_lft 299sec
inet6 fe80::baa1:881a:aa:cbca/64 scope link
valid_lft forever preferred_lft foreverIn our example, the IPv4 IP address of the Pi is 10.0.0.185
2. In a web browser, use the IP address you just found like this http://<YOUR IP>. In our example above, the IP is 10.0.0.185, so we would enter http://10.0.0.185 into our web browser.
|
3. You've arrived! From here, you can insert/eject CD-ROM images, upload new disk images to the Raspberry Pi, or create new blank hard disk images. It should look similar to the following screenshot:
|
If your Mac has a network connection, and can communicate with your Raspberry Pi, you can manage PiSCSI from that computer.
The functionality of the web interface has been tested with the following "vintage" web browsers. The formatting doesn't look as good as a modern browser, but its still fully usable!
- Netscape 3.x
- Netscape 4.8.x
- MacWeb 2.0
As of v21.11.01, PiSCSI has opt-in Web Interface user authentication. While the Web Interface still communicates over unencrypted http, this won't protect against sophisticated malicious users and network sniffing, it does protect against casual attacks and misuse.
Note: The below process has been automated in the easyinstall.sh script. Launch the script and choose the enable authentication for the PiSCSI Web Interface option to enable authentication and grant access to the user who launched the script.
The Web Interface will enable authentication if the piscsi group exists on the system.
$ sudo groupadd piscsiOnly users who are members of this group will be allowed to authenticate in the Web Interface. This is an example for the pi user:
$ sudo usermod -a -G piscsi piNow when you load the Web Interface, you should see a login form in the header of the page. The login session will be stored in a browser cookie and retained as long as the cookie is alive. Use the Log Out function in the header to terminate the session.
When authentication is enabled, anonymous users will only be able to carry out certain basic actions such as viewing device info or accessing PiSCSI logs.