Skip to content

Web Interface

Daniel Markstedt edited this page Apr 27, 2023 · 34 revisions

Security Notice!

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.

Table of Contents

Setup PiSCSI Web Interface

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

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

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

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

After 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 pi

5. 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/piscsi

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

Using the Web Control Interface

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

In 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:

Using the web interface directly from your Mac

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

Enable Authentication

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 piscsi

Only 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 pi

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

Clone this wiki locally