https://github.com/bkahlert/libguestfs
Containerized libguestfs including virt-customize, guestfish, etc.
https://github.com/bkahlert/libguestfs
docker guestfish libguestfs shellscript virt-builder virt-customize
Last synced: 2 months ago
JSON representation
Containerized libguestfs including virt-customize, guestfish, etc.
- Host: GitHub
- URL: https://github.com/bkahlert/libguestfs
- Owner: bkahlert
- License: mit
- Created: 2020-12-28T05:33:11.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-29T20:30:26.000Z (over 1 year ago)
- Last Synced: 2025-04-12T04:58:29.030Z (2 months ago)
- Topics: docker, guestfish, libguestfs, shellscript, virt-builder, virt-customize
- Language: Shell
- Homepage:
- Size: 26.4 MB
- Stars: 24
- Watchers: 2
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# bkahlert/libguestfs [](https://github.com/bkahlert/libguestfs/actions/workflows/build.yml) [](https://github.com/bkahlert/libguestfs) [](https://github.com/bkahlert/libguestfs/blob/master/LICENSE)
## About
**Containerized libguestfs including virt-customize, guestfish, etc.**
* Runs as non-root user
* Multi-platform image
* Helper scripts
* [`guestfish` *Manipulate a virtual machine / image using the guest filesystem shell*
](../../raw/master/docs/guestfish.svg)
* [`virt-builder` *Build virtual machine images quickly*
](../../raw/master/docs/virt-builder.svg)
* [`virt-customize` *Customize a virtual machine / image*
](../../raw/master/docs/virt-customize.svg)
* [`pi` *Boot a virtual machine / image using a dockerized ARM emulator that emulates a Raspberry Pi*
](../../raw/master/docs/pi.svg)
* [`copy-out` *Copy files out of a virtual machine / image*
](../../raw/master/docs/copy-out.svg)
## Build locally
```shell
git clone https://github.com/bkahlert/libguestfs.git
cd libguestfs
# Build image and output to docker (default)
docker buildx bake
# Build multi-platform image
docker buildx bake image-all
```
## Image
* [Docker Hub](https://hub.docker.com/r/bkahlert/libguestfs/) `bkahlert/libguestfs`
* [GitHub Container Registry](https://github.com/users/bkahlert/packages/container/package/libguestfs) `ghcr.io/bkahlert/libguestfs`
Following platforms for this image are available:
- linux/amd64
- linux/arm/v7
- linux/arm64/v8
- linux/ppc64le
- linux/riscv64
- linux/s390x
## Usage
### Interactively
```shell
docker run -it --rm \
-v "$PWD":"$PWD" \
-w "$PWD" \
bkahlert/libguestfs:edge \
guestfish
> add disk.img format:raw
> launch
> mount /dev/sda ./
> ls /
> copy-out /boot data
> umount-all
> exit
```
### Automatically
```shell
docker run -i --rm \
-v "$PWD":"$PWD" \
-w "$PWD" \
bkahlert/libguestfs:edge \
guestfish \
--ro \
--add disk.img format:raw \
--mount /dev/sda:/ \
< 💡 Did you notice the leading dash in front of the `copy-out` command? Running guestfish non-interactively the first command that gives an error causes the
> whole shell to exit. By prefixing a command with `-` guestfish will not exit if an error is encountered.
> 💡 If you prefix a command with `!` (e.g. `!id`) the command will run on the host instead of the mounted guest. Since the libguestfs tools are containerized
> themselves, "host" signifies the containerized libguestfs hosting Ubuntu installation — and not you actual OS.
## Configuration
This image can be configured using the following options of which all but `APP_USER` and `APP_GROUP` exist as both—build argument and environment variable.
You should go for build arguments if you want to set custom defaults you don't intend to change (often). Environment variables will overrule any existing
configuration on each container start.
- `APP_USER` Name of the main user (default: `libguestfs`)
- `APP_GROUP` Name of the main user's group (default: `libguestfs`)
- `DEBUG` Whether to log debug information (default: `0`)
- `TZ` Timezone the container runs in (default: `UTC`)
- `LANG` Language/locale to use (default: `C.UTF-8`)
- `PUID` User ID of the `libguestfs` user (default: `1000`)
- `PGID` Group ID of the `libguestfs` group (default: `1000`)
- `LIBGUESTFS_DEBUG` Set this to 1 in order to enable massive amounts of debug messages. If you think there is some problem inside the libguestfs appliance,
then you should use this option. (default: `0`)
- `LIBGUESTFS_TRACE` Set this to 1 and libguestfs will print out each command / API call in a format which is similar to guestfish commands. (default: `0`)
```shell
# Build single image with build argument TZ
docker buildx bake --set "*.args.TZ=$(date +"%Z")"
# Build multi-platform image with build argument TZ
docker buildx bake image-all --set "*.args.TZ=$(date +"%Z")"
# Start container with environment variable TZ
docker run --rm \
-e TZ="$(date +"%Z")" \
-v "$(pwd):$(pwd)" \
-w "$(pwd)" \
libguestfs:local
```
## Testing
```shell
git clone https://github.com/bkahlert/libguestfs.git
cd libguestfs
# Use Bats wrapper to run tests
curl -LfsS https://git.io/batsw |
DOCKER_BAKE="--set '*.tags=test'" bash -s -- --batsw:-e --batsw:BUILD_TAG=test test
```
[Bats Wrapper](https://github.com/bkahlert/bats-wrapper) is a self-contained wrapper to run tests based on the Bash testing
framework [Bats](https://github.com/bats-core/bats-core).
> 💡 To accelerate testing, the Bats Wrapper checks if any test is prefixed with a capital X and if so, only runs those tests.
## Troubleshooting
If you run into problems, try running your intended steps interactively with verbose logging turned on:
```shell
docker run -it --rm \
-e "LIBGUESTFS_DEBUG=1" \
-e "LIBGUESTFS_TRACE=1" \
-v "$PWD":"$PWD" \
-w "$PWD" \
bkahlert/libguestfs:edge \
guestfish
```
To debug the image the following lines might become handy:
```shell
# build local image with specified tag
docker buildx bake --set '*.tags=test'
# copy something to test with
cp test/fixtures/tinycore.iso disk.img
# start container interactively with a bash
docker run \
-e LIBGUESTFS_DEBUG=1 \
-e LIBGUESTFS_TRACE=1 \
-e DEBUG=1 \
-e TZ=CET \
-e PUID=68039910 \
-e PGID=584555228 \
-e TERM=xterm-256color \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$PWD":"$PWD" \
-w "$PWD" \
--interactive \
--tty \
--rm \
--entrypoint /bin/bash \
--name libguestfs-test \
test
# fixes (normally performed by entrypoint.sh)
chmod 0644 /boot/vmlinuz*
usermod -a -G kvm "$(whoami)"
# run guestfish interactively
guestfish
# or as root: (see entrypoint_user.sh for details)
LIBGUESTFS_BACKEND=direct guestfish
# run guestfish using the original entrypoint
entrypoint.sh guestfish \
--ro \
--add disk.img format:raw \
--mount /dev/sda:/ \
<