Last updated 03-11-2025
Piserver automates the technical aspects of setting up a classroom of computer workstations or a library with public access workstations. It differs in one very important way from zero client and thin client solutions. It is more efficient to run programs locally on a Raspberry Pi than to have the server run apps and send the client workstations compressed pixels or X-server primitives to display. The Raspberry pi 4B has hardware graphic acceleration so you reduce network traffic and eliminate client use of the server CPU and GPU this way. This allows the server to support more clients. The client does not need any local storage because that is on the server and it network boots from the server. You don’t have to configure a microSD card with the OS for each of the clients – this saves material cost and time. The Raspberry Pi 4B is also less expensive than a new zero or thin client device. It can support dual 4K displays.
This project was initiated by the UK registered educational charity:
https://static.raspberrypi.org/files/about/RaspberryPiFoundation_Theory_of_Change_Summary_2024.pdf
and their volunteer programmers and is intended to run on Raspberry Pi models 3B+, 4B, and Pi 400 keyboard (which have a built in Pi4B) manufactured by their affiliated non-profit. https://en.wikipedia.org/wiki/Raspberry_Pi All software is opensource and free and the hardware is sold at cost.
In line 23 of the source file, config.h, you can see that it supports these 4 MAC address prefixes so it would be easy to add additional models when and if they become available.
#define OUI_FILTER “^(b8:27:eb|dc:a6:32|e4:5f:01|d8:3a:dd):”
The project started before the pandemic. There were supply chain problems during the pandemic so the hardware became scarce and the documentation was spread around forums, much of which has become outdated. In what follows I will document how to install it. I will assume that the reader skill level includes having installed an OS on a standalone Raspberry pi. Some of my asides are not required to successfully compete the installation but may be of interest.
https://github.com/raspberrypi/piserver
The most recent piserver_0.7.6.deb_i386.deb is 255 KB dated May 16, 2023. This is for Debian Bullseye, not the most recent Debian Bookworm that the new Pi 5 and Pi 500 require. But you don’t need a Pi 5 for a client workstation, so this is not really a problem. The server requires fast storage and lots of it if you are setting up 100 clients and perhaps more than a 100 students or library users who each will have personal storage on the server under their private home directories. That is why the piserver install candidate expects to run on an i386 compatible processor. For a home server, you could use just another Pi 4B, so I tried building the piserver for a Pi and found that the build instructions are flawless for a host server running Bullseye in either the 32 or 64 bit versions, but either way the build of piserver will result in a 32 bit, not 64 bit, build and it will not build for Bookworm without major revisions of the source files and build instructions because of dependencies that have changed between Bullseye and Bookworm Debian Linux.
Conveniently, the legacy Bullseye OS needed to run the piserver on a i386 computer is still available in 32 bit full desktop version dated July 1, 2022 (scroll down to the bottom of this link).
https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-desktop
Once you have installed the Debian 32 bit full desktop and downloaded the piserver_0.7.6_i386, you install it with the terminal command,
sudo dpkg -i piserver_0.7.6_i386
and all the technically hard stuff completes automatically.
Once installed piserver will be found in the current Raspberry Pi OS under the menu category “Preferences. ” By default it is enabled once the computer has booted. It is definitely a convenience to be running a desktop, but once configured, you can have the computer only boot to the login prompt and don’t even need to login. Piserver can export a GUI piserver interface to any of the Pi clients running a desktop. The server could be in a physically secure utility closet with no monitor, keyboard, or mouse.
The next step requires that at least one client pi is configured to boot from the network, is attached to the same network, and is turned on. The GUI administrative configuration will not let you proceed until it finds one PI client on the same network. You will need one bootable pi os microSD to configure each workstations firmware to boot over the network. Once booted from this microSD card, go to terminal (full destop version) or in the lite version, execute sudo raspi-config and you will get this menu:
Click on this top selection to get this menu:
Click OK and ESC back to the command line. You must reboot once to get this change written to firmware. Then shutdown, remove the microSD card and power off and back on to reboot into network booting mode. In network booting mode, it will always first check for a microSD card which would override network booting if found. So it is easy to use now in either mode.
If you are using just another raspberry pi 4B for the server, it would be a good time to use it to sudo raspi-config again and use the option to enable SSH as well as change the piserver computer hostname to piserver. I am assuming that its username is pi and that its hostname is piserver in my scripts below.
The first time you open the piserver GUI you get an introduction and need to click next.
The left hand panel shows the order of the initial configuration steps. You have to click the Next button to move through the steps. Once finished, you can revisit any of the steps in any order by clicking on the step.
I have one pi 4B client connected from which I am writing this. Initially you will not see the OS assigned to that client because that is a later step.
Now we need at least one client user. I have configured two. If you click on a user and then edit, you can specify or change their password as well as enter descriptive information like their real name, student ID, or library card number.
Now we need to install at least one OS for the clients:
I have two OS installed, the full Desktop version and the lite command line only version. But let’s backup a step to how you install these OS. If you click the add button you get this menu:
Notice the check box at the top, install operating system from repository. You have 6 choices (scroll bar if hover over with mouse). In most use cases, you would choose the Full (64 bit) Desktop which installs a lot of applications. However, you might prefer to install the (64 bit) and then add applications separately and if your students are interested in writing computer programs, you might want to also install the lite (64 bit) version to exercise their basic Linux skills.
Some explanation is needed for the other three options, so you can skip ahead if this doesn’t interest you. In a standalone Pi computer booting off its local microSD card, there are two partitions, a bootfs partition for hardware specific drivers and firmware, and a rootfs partition for the LInux OS, all application programs, and the users personal files. If you are setting up a 100 client computer classroom, it makes no sense to have an individual copy of the bootfs and OS for every user or every workstation. Therefore, piserver converts the standard microSD card image to separate the read only part of the OS to avoid duplication. Each installed client OS is a separate subdirectory on the piserver rootfs partition. The user home directories are read write for the user and only visible to the user and the administrator. One user can not see any other users’ files, nor can they alter the piserver installation except for specific things like a preference for their personal desktop background, etc. There is also a special shared directory that all users can read, but only the administrator/teacher can write to. This could be used for class syllabi, etc. The administrator/teacher can create subdirectories in this shared folder to organize material by grade level and subject. Because converting a standard boot microSD card to how piserver works is quite technical, you would not normally attempt to do this and would only install from the repository shown whose compressed files are in the format of .tar.xz instead of .img.xz.
Two images above you saw Export and Clone buttons. Clone makes a backup copy of the OS and its installed programs. Export allows you to write out any OS and its applications to a single file in .tar.xz format. You might want to do this and save this file for perhaps another installation on some other computer network, or so you can revert to a version you like if the needs of your students change and you don’t want all the programs you have installed since your last backup cloning.
Having Exported a backup, you then use the “import from local file (tar.xz) to restore the cloned image previously exported.
If you stored your backup .tar.xz file on a web server with a URL for it, or on a microSD card, then the last two options are useful. But you do not use the import from microSD card to convert a standard standalone bootable .img.xz to .tar.xz to import.
The Update button is currently inactive. I imagine it was intended to allow updating all your installed OS with a single click per OS if more recent versions became available in the repository.
Remember that users on client computers do not have root privileges which prevents them from installing, by accident or intention, malware and that no one on the clients has root privileges to update or add new software, so how does the administrator do this? Looking back on the Software menu, notice the Shell button in the upper right corner.
Clicking on the Shell button opens a root terminal on the installed OS that I highlighted. The administrator can then install any upgrades to parts of the OS and install and uninstall application programs. How this works is quite technical because a chroot changes the apparent root directory for a process and its children, which in this case is to a specific OS of the several coexisting on the server computer. With piserver this does not require any expertise, just the standard commands you would use on a standalone system.
Here you see the menu for adding shared folders. I have added sub folders for 4 grades using the Add button.
At this point the directory tree for piserver with two OS looks like this:
Separately here are the home directories. pi is the administrator account with sudo root privileges. pi2b and pi2b-2 are two user accounts who do not have root privileges to anything, but they can save and edit files from any source in their private home directories. Note that Cloning (backing up an OS) does not backup any user files. All user files are per user and independent of which workstations they have logged into, or which OS version has been assigned to any of these workstations. Thus the administrator home (and root) sub directories is a separate backup step, as are the home sub directories of each user. The administrator can backup up user home sub directories, or that could be left as a responsibility of each user who can backup their files to a USB flash drive that they own which they might well want to do so as to access their content on their home computer.
Finally the Settings menu. I did not have to change any of the defaults.
You either need to configure piserver for a static address, or as in my case, my OpenWrt router and network switch assign the network leases predictably based on which switch port the server is connected to so my piserver is always given the same dynamic IP address as it had when installed without specifically being static.
Note the default, Act as proxy DHCP server. There can only be one DHCP server. If your router is acting as a DHCP server, then you must set piserver here as a proxy DHCP server which will only handle your raspberry pi clients. Piserver installation configured the proper default and I didn’t have to change anything.
Having completed the preliminary configuration, we get this page while it is setting up our configuration.
At the beginning I mentioned that piserver did not need a GUI desktop when running. You should use sudo raspi-config to change the server boot option to CLI, no login. This will let the server do its job without the services required to manage a GUI desktop that isn’t being used. Again in terminal, sudo raspi-config:
Click on my selection:
Change the default login to CLI and require password. When piserver boots next it will not waste time setting up a desktop and no user will be logged into the server computer, but piserver will be running and available to boot all the configured client workstations over the network.
At any point during this installation or afterwards, it would be good to replace the default host name of raspberrypi on the server to something else like piserver and enable SSH. Then you will be able to change the configuration of piserver remotely with ssh pi@piserver and not have to remember or specify the IP address of the piserver hosting it.
You can not change a hostname of a client, from a client, because clients don’t have root privileges. Since port 22 is closed for clients, you will not be ssh’ing into a client either. Each Pi 4B is uniquely identified by its MAC network hardware address so it doesn’t matter that all clients have the same default hostname, raspberrypi.
I have written this whole documentation on a client Pi 4B with 2 GB of memory from a user account, pi2b. I used GIMP to crop the screenshot images and convert from .png to .jpg. I used an online panorama creator to stitch together a series of terminal images into one image, but I could have used the Hugin Panorama Creator if I had researched what focal length to use for screenshots. I used LibreOffice Writer to import this web page and convert it to .pdf format. All this software and the OS is opensource and free. I host this WordPress site on Blue Host.
A user account does not have root privileges. However, a user account can SSH into another computer in the network (piserver) if it knows the password and username of the administrator account. The -X causes any GUI program output to be imported. The -E causes the piserver GUI interface to be exported. Thus the administrator can use any computer on the network, including the diskless client work stations, to configure piserver and piserver does not need to boot to a Desktop nor have a monitor, keyboard, or mouse connected to it. This highlights the importance of a long random password with a large alphabet (lower and upper case letters, digits, and the special characters, ~!@#$%^&*()_+`{}|[]\:”;'<>?,./
There should be no words in the password that are in the dictionary. The characters should not have a pattern like qwertyuiop[]\ which is just a row of my keyboard which makes them easy to remember but they are not random, so easy to guess.
You can also generate: authorized_keys, id_rsa, id_rsa.pub, known_hosts as I explain: https://raspiplayer.com/x2go/
Piserver will warn you it you try to power off when there are still client computer workstations logged in. This can be overridden, but I would think that each client should be logged out before the piserver is shut down.
Since piserver should be in a physically secure room or utility closet to protect user data. It is a convenience to be able to shut it down from one of the clients so here is a script to do that. The script assumes that the hostname of the server is piserver. It also assumes that you have set up public-key cryptography so that you get secure auto authentication so you can ssh into the piserver without having to be there to login.
When I execute this script from my network booted client, it responds with these messages. First, piserver reports it has scheduled shutdown in 2 minutes, then my router reports that it has powered down, then my client workstation reports that it has scheduled shutdown in 1 minute ( it must shutdown before piserver). The order of shutdowns is important. The router is needed to find piserver so can’t be shutdown before piserver schedules shutdown. All the clients need to shutdown before piserver or it will object that some users are logged in still.
Piserver has information on all active client stations, so how to shut them each down should have been a built in command of piserver. I only have one client, so this little script works for me. Piserver doesn’t currently let anyone ssh into any of the clients, so I will have to figure out a different way so that the admin doesn’t have to physically go to each client workstation and make sure it is logged out and shutdown.
Piserver is compatible with a web based library catalog and member accounts. Piserver could have a web server for delivering this content and user interaction with this content as well as an interactive library catalog database.
Any professional service provider including retail point of sales terminals, should only be running on diskless workstations so that if the workstation is stolen, the thief gets no private data.
Future ideas:
1) I get my internet from usb tethering my phone. I have set up an openwrt router and network switch to share that internet with additional computers in my LAN. The router could be built into the piserver or piserver could be built into the router given appropriate hardware to run both on.
2) As originally conceived, piserver was to run on an Intel cpu, but the clients run on arm cpus. That dictated that there would be at least two OS, the OS supporting piserver and the OS that the arm cpu clients boot from. If the server is on just another Raspberry pi, there is an unnecessary duplication of two OS which are mostly the same except for some settings per user and per workstation. Removing that redundancy would mean only one OS requires periodic updates instead of two.
3) Build a new system supporting the newer Bookworm OS for both server and clients.
4) Build into the server a capability to logout and shutdown all the clients except perhaps a current client that remotely can shutdown itself after telling the server to shutdown all the others.