Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@oxzi
oxzi committed Sep 23, 2021
1 parent f08f3c0 commit 6dcb52f
Showing 1 changed file with 57 additions and 56 deletions.
113 changes: 57 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,53 @@
[![tests](https://github.com/Nature40/pimod/workflows/tests/badge.svg?branch=master)](https://github.com/Nature40/pimod/actions?query=workflow%3Atests)
[![shellcheck](https://github.com/Nature40/pimod/workflows/shellcheck/badge.svg?branch=master)](https://github.com/Nature40/pimod/actions?query=workflow%3Ashellcheck)

Reconfigure Raspberry Pi images with an easy, Docker-like configuration file. For detailed information [read our paper](https://jonashoechst.de/assets/papers/hoechst2020pimod.pdf).
Reconfigure Raspberry Pi images with an easy, Docker-like configuration file.


## About
*pimod* overtakes a given Raspberry Pi image by mounting a copy and modifying
this copy through QEMU chroot. Therefore one can execute Pi's ARM-code easily
on its x86\_64 host.
*pimod* overtakes a given Raspberry Pi image by mounting a copy and modifying this copy through QEMU chroot.
Therefore one can execute Pi's ARM-code easily on its x86\_64 host.

```
# Create a customized version of the Raspberry Pi OS Lite
FROM 2020-05-27-raspios-buster.img
TO raspbian-buster-upgraded.img
# Increase the image by 100 MB
PUMP 100M
# Enable serial console using built-in configuration tool
RUN raspi-config nonint do_serial 0
# Upgrade the operating system image
RUN apt-get update
RUN bash -c 'DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade'
# Install an ssh key from local sources
INSTALL id_rsa.pub /home/pi/.ssh/authorized_keys
```

For detailed information [read our paper](https://jonashoechst.de/assets/papers/hoechst2020pimod.pdf).


## Installation, Usage
### Debian
```bash
$ sudo apt-get install binfmt-support fdisk file kpartx lsof parted qemu qemu-user-static unzip p7zip-full wget xz-utils

$ sudo ./pimod.sh Pifile
sudo apt-get install binfmt-support fdisk file kpartx lsof parted qemu qemu-user-static unzip p7zip-full wget xz-utils
sudo ./pimod.sh Pifile
```

### Docker
```bash
# build the docker container
$ docker build -t pimod .
docker build -t pimod .

# run the container privileged to allow loop device usage
$ docker run --rm --privileged -v $PWD:/pimod pimod pimod.sh examples/RPi-OpenWRT.Pifile
# run the container privileged to allow loop device usage or…
docker run --rm --privileged -v $PWD:/pimod pimod pimod.sh examples/RPi-OpenWRT.Pifile

# alternatively use docker-compose
$ docker-compose run pimod pimod.sh examples/RPi-OpenWRT.Pifile
# …alternatively use docker-compose
docker-compose run pimod pimod.sh examples/RPi-OpenWRT.Pifile
```

### GitHub Actions
Expand All @@ -45,19 +65,19 @@ jobs:
with:
submodules: recursive
- name: Run pimod OpenWRT example
uses: Natur40/pimod@v0.2.1
uses: Natur40/pimod@master
with:
pifile: examples/RPi-OpenWRT.Pifile
```
## Pifile
The *Pifile* contains commands to modify the image. However, the *Pifile*
itself is just a Bash script and the commands are functions, which are loaded
in different stages.
The Pifile contains commands to modify the image.
However, the Pifile itself is just a Bash script and the commands are functions, which are loaded in different stages.
### Example
```bash
```
$ cat Upgrade.Pifile
FROM 2018-11-13-raspbian-stretch-lite.img

Expand All @@ -80,77 +100,58 @@ $ sudo ./pimod.sh Upgrade.Pifile
$ dd if=Upgrade.img of=/dev/sdc bs=4M status=progress
```

More examples are available in the
[Sensorboxes](https://github.com/Nature40/Sensorboxes) repository.


### Commands
#### `FROM [PATH_TO_IMAGE]`, `FROM [URL|`
`FROM` sets the `SOURCE_IMG` variable to a target. This might be a local file or
a remote URL, which will be downloaded. This file will become the base for
the new image.
`FROM` sets the `SOURCE_IMG` variable to a target.
This might be a local file or a remote URL, which will be downloaded.
This file will become the base for the new image.

#### `TO [PATH_TO_IMAGE]`
`TO` sets the `DEST_IMG` variable to the given file. This file will contain
the new image. Existing files will be overridden.

Instead of calling `TO`, the Pifile's filename can also indicate the output
file, if the Pifile ends with *".Pifile"*. The part before this suffix will be
the new `DEST_IMG`.
`TO` sets the `DEST_IMG` variable to the given file.
This file will contain the new image.
Existing files will be overridden.

If neither `TO` is called nor the Pifile indicates the output, `DEST_IMG` will
default to *rpi.img* in the source file's directory.
Instead of calling `TO`, the Pifile's filename can also indicate the output file, if the Pifile ends with *".Pifile"*.
The part before this suffix will be the new `DEST_IMG`.

If neither `TO` is called nor the Pifile indicates the output, `DEST_IMG` will default to *rpi.img* in the source file's directory.

#### `INPLACE [PATH_TO_IMAGE]`
`INPLACE` does not create a copy of the image, but performs all further
operations on the given image. This is an alternative to `FROM` and `TO`.
`INPLACE` does not create a copy of the image, but performs all further operations on the given image.
This is an alternative to `FROM` and `TO`.

#### `INCLUDE [PATH_TO_PIFILE]`
`INCLUDE` includes the provided Pifile in the current one for modularity and
re-use. The included file _has_ to have a `.Pifile` extension which need not be
specified.

`INCLUDE` includes the provided Pifile in the current one for modularity and re-use.
The included file _has_ to have a `.Pifile` extension which need not be specified.

#### `PUMP [SIZE]`
`PUMP` increases the image's size about the given amount (suffixes K, M, G are allowed).

#### `INSTALL <MODE> [SOURCE] [DEST]`
`INSTALL` installs a given file or directory into the destination in the
image. The optionally permission mode (*chmod*) can be set as the first
parameter.
`INSTALL` installs a given file or directory into the destination in the image.
The optionally permission mode (*chmod*) can be set as the first parameter.

#### `PATH [/my/guest/path]`
`PATH` adds the given path to an overlaying PATH variable, used within the `RUN`
command.
`PATH` adds the given path to an overlaying PATH variable, used within the `RUN` command.

#### `RUN [CMD] [PARAMS ...]`
`RUN` executes a command in the chrooted image based on QEMU user emulation.

Caveat: because the Pifile is just a Bash script, pipes do not work as one
might suspect. A possible workaround could be the usage of `bash -c`:
Caveat: because the Pifile is just a Bash script, pipes do not work as one might suspect.
A possible workaround could be the usage of `bash -c`:

```bash
```
RUN bash -c 'hexdump /dev/urandom | head'
```

#### `HOST [CMD] [PARAMS ...]`
`HOST` executed a command on the local host and can be used to prepare files, cross-compile software, etc.



### Pifile Extensions
Because the *Pifile* is just a Bash script, some ~~dirty~~ brilliant hacks and extensions are possible.


#### Inherit another Pifile
Another *Pifile* can be extended by sourcing it in the first line.

```bash
source Parent.Pifile
```


#### Bulk execution
Here documents can be used with the `RUN` command.

Expand All @@ -174,7 +175,6 @@ EOF
```

## Scientific Usage & Citation

If you happen to use pimod in a scientific project, we would very much appreciate if you cited [our scientific paper](https://jonashoechst.de/assets/papers/hoechst2020pimod.pdf):

```bibtex
Expand All @@ -195,3 +195,4 @@ If you happen to use pimod in a scientific project, we would very much appreciat
- [raspberry-pi-chroot-armv7-qemu.md](https://gist.github.com/jkullick/9b02c2061fbdf4a6c4e8a78f1312a689)
- [chroot-to-pi.sh](https://gist.github.com/htruong/7df502fb60268eeee5bca21ef3e436eb)
- [PiShrink](https://github.com/Drewsif/PiShrink)
- [pi-bootstrap](https://github.com/aniongithub/pi-bootstrap)

0 comments on commit 6dcb52f

Please sign in to comment.