Pieman

<p align="center"> <img src="/logo/380x400.png" alt="Pieman"> </p>

Pieman is a script for creating custom OS images for single-board computers such as Raspberry Pi and Orange Pi. The authors of Pieman were inspired by the project named rpi23-gen-image. The main reason why it was decided to create a new project instead of improving the existing one is that rpi23-gen-image is intended for creating images only for Raspberry Pi 2 and 3 based on Debian GNU/Linux. Unfortunately, it doesn't have a way to be extended to support different operating systems and single-board computers. Improving the situation would require significant efforts to rework the codebase of the project.

The project is named after a superhero Pie Man appeared in the Simpsons' episode Simple Simpson.

Pieman is a core component of CusDeb.

Features

• The images can be based on Alpine and Debian-based distributions such as Kali, Raspberry Pi OS (formerly Raspbian) and Ubuntu.
• 64-bit images based on Ubuntu.
• OTA updates via Mender.

Table of Contents

• Supported Devices and OSes
• Getting Started
  • Dependencies
    • Mandatary
    • Optional
  • Supported platforms
  • Installation
    • Docker
    • Manual
• Running tests
• Documentation
  • Parameters
    • General
    • Networking
    • Package manager
    • Users
    • Image
    • Pieman-specific
    • Extra
  • Storing parameters in .env file
• Running images in emulator
• FAQ
• Authors
• Licensing
• Contribute

Supported Devices and OSes

| | _{Alpine 3.12} | _{Debian 10 «Buster»} | _{Kali Linux Rolling} |_{Raspberry Pi OS 10 «Buster»} | _{Ubuntu 16.04 «Xenial Xerus»} | _{Ubuntu 18.04 «Bionic Beaver»} | _{Ubuntu 20.04 «Focal Fossa»} | |---------------------------------------------------------------------------------------------------------------------|:---------------------:|:-----------------------------:|:-------------------------------:|:-------------------------------:|:--------------------------------------:|:---------------------------------------:|:-------------------------------------:| | _{Orange Pi <a href="http://orangepi.org/orangepipcplus/">PC Plus</a>} | | _32bit | _32bit | | | | | | _{Orange Pi <a href="http://www.orangepi.org/orangepizero/">Zero</a>} | | _32bit | _32bit | | | | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-1-model-b/">Model B and B+</a>} | | | | _32bit | | | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-2-model-b/">2 Model B</a>} | _32bit | | | _32bit | _32bit | _32bit | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-3-model-b/">3 Model B</a>} | _32bit | | | _32bit | | _{32bit, 64bit} | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/">3 Model B+</a>} | _32bit | | | | | _32bit | _32bit | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-4-model-b/">4 Model B</a>} | | | | _32bit | | | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-zero/">Zero</a>} | | | | _32bit | | | | | _{Raspberry Pi <a href="https://www.raspberrypi.org/products/raspberry-pi-zero-w/">Zero W</a>} | | | | _32bit | | | |

Getting Started

Dependencies

Mandatary

• Development tools
  • GNU Bison
  • C programming language compiler
  • Flex
  • Git
  • Make
  • SWIG
• Python
  • Development libraries and header files related to Python 2.7
  • Python 2.7
  • Python 3 (3.5 or higher)
  • Setuptools
• Utils
  • dosfstools
  • dpkg
  • GNU Parted
  • GnuPG
  • mkfs.ext4
  • rsync
  • User mode emulation binaries such as /usr/bin/qemu-arm-static and /usr/bin/qemu-aarch64-static
  • xz

Note that installing qemu-user-static is not enough in Debian/Ubuntu. You also have to install binfmt-support.

Here are the commands to install the mandatory dependencies

• on Debian or Ubuntu

  $ sudo apt-get install binfmt-support bison dosfstools flex gcc git gnupg make parted python-dev python3-pip python3-setuptools qemu-user-static swig rsync xz-utils
  

• on Fedora

  $ sudo dnf install bison dosfstools dpkg e2fsprogs flex gcc git gpg make parted python2-devel python3-pip python3-setuptools qemu-user-static rsync swig xz
  

Optional

• To enable COMPRESS_WITH_BZIP2: bzip2
• To enable Mender support:
  • Development libraries and header files related to C standard library (make sure the package, which is going to be installed to satisfy the dependency, includes /usr/include/sys/types.h)
  • Go programming language compiler
  • bc
  • dtc

Here are the commands to install the optional dependencies

• on Debian or Ubuntu

  sudo apt-get install bzip2 bc gcc device-tree-compiler golang libc6-dev-i386
  

• on Fedora

  sudo dnf install bc bzip2 dtc golang
  

Supported platforms

Theoretically, Pieman can be run on any GNU/Linux, however, it was very carefully tested only on:

• Debian 9 «Stretch»
• Fedora 29
• Ubuntu 16.04 «Xenial Xerus»
• macOS 10.13 «High Sierra» (running Pieman in the official Docker container)

Installation

Docker

First, make sure that the following requirements are satisfied:

• Bash 4 or higher;
• qemu-user-static and binfmt-support on Debian or Ubuntu;
• qemu-user-static on Fedora.

Next, get the latest Pieman Docker image from Docker Hub.

$ docker pull cusdeb/pieman

Then, get docker-pieman.sh

$ wget https://raw.githubusercontent.com/tolstoyevsky/pieman/master/docker-pieman.sh -O docker-pieman.sh

or using curl

$ curl -O https://raw.githubusercontent.com/tolstoyevsky/pieman/master/docker-pieman.sh

Finally, go to the next section to know how to use the script.

Usage

Simply run docker-pieman.sh to create an image based on Raspberry Pi OS Buster for Raspberry Pi 3.

$ chmod +x docker-pieman.sh
$ ./docker-pieman.sh

Under the hood the script runs

$ docker run --privileged --rm -v $(pwd):/result -v /dev:/dev cusdeb/pieman

It's quite wordy, isn't it? docker-pieman.sh is intended to hide the details and provide an easy-to-use command-line interface.

Another example shows how to create an image based on Ubuntu Xenial for Raspberry Pi 2 with [htop](htt