Metadata-Version: 2.4
Name: pixiefairy
Version: 0.2.1
Summary: Pixiefairy a Pixiecore API server companion
License-Expression: Apache-2.0
Author: Manuel Bovo
Author-email: manuel.bovo@gmail.com
Requires-Python: >=3.14,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: PyYAML (>=6.0.3,<7.0.0)
Requires-Dist: click (>=8.4.2,<9.0.0)
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: fastapi (>=0.141.1,<0.142.0)
Requires-Dist: gevent (>=26.8.0,<27.0.0)
Requires-Dist: loguru (>=0.7.3,<0.8.0)
Requires-Dist: pydantic (>=2.13.4,<3.0.0)
Requires-Dist: pydantic-yaml (>=1.7.0,<2.0.0)
Requires-Dist: shellingham (>=1.5.4,<2.0.0)
Requires-Dist: typer (>=0.27.1,<0.28.0)
Requires-Dist: urllib3 (>=2.7.0,<3.0.0)
Requires-Dist: uvicorn (>=0.52.4,<0.53.0)
Project-URL: Repository, https://github.com/mbovo/pixiefairy
Description-Content-Type: text/markdown

# Pixie Fairy - a Pixiecore API companion

[![](https://img.shields.io/pypi/v/pixiecore.svg)](https://pypi.org/pypi/pixiefairy)
[![Tag and build](https://github.com/mbovo/pixiefairy/actions/workflows/build-image.yaml/badge.svg)](https://github.com/mbovo/pixiefairy/actions/workflows/build-image.yaml)

`Pixiefairy` is a companion for [pixiecore](https://github.com/danderson/netboot/tree/master/pixiecore) a tool to manage network booting of machines.
`Pixiecore` in [API mode](https://github.com/danderson/netboot/tree/master/pixiecore#pixiecore-in-api-mode) send a request to an external service for each pxe booting event; *pixiefairy* is that service, answering to api calls and serving the configured info, like the kernel, the initrd and the command line to boot.

`Pixiefairy` is higly configurable, you can decide which mac-address and which set of parameters to serve to each client.

## Installation

Pixiefairy requires `python >= 3.9`
It's as easy as

```bash
pip3 install pixiefairy
```

Then you will have available the `pixiefairy` binary

## Usage

Pixiefairy can be started using the `start` command. It requires a config.yaml file with a bunch of defaults in order to know how to serve the requests.

```bash
pixiefairy start -c config.yaml
```

## Configuration

An example configuration can be found into [examples/config.yaml](./examples/config.yaml) like

```yaml
defaults:
  boot:
                # the kernel to boot into
    kernel: "file:///root/vmlinuz-amd64"
    initrd:     # the list of initrd files to load at boot
      - "file:///root/initramfs-amd64.xz"
    message: "" # optional, a boot message
    cmdline: "" # optional, the command line to boot
  net:
    dhcp: true                 # use dhcp or send n ip=.... kernel parameters to configure the network
    gateway: "192.168.1.0"     # the default gateway to send to the requestor
    netmask: "255.255.255.0"   # the netmask to send to requestor
    dns: "8.8.8.8"         # default dns server
    ntp: "192.168.1.0"         # default ntp server
  deny_unknown_clients: false  # either boot unknown clients or boot only the mac address listed in mapping below
mapping:  # optional
  aa:bb:cc:dd:ee:ff:  # the matching mac address
    net: null             # net block, optional, identical to the net block in defaults, override
    boot: null            # boot block, optional, identical to the boot block in defaults, override
```

## Dev Requirements

In order to participate in development you need the following requirements:

- [just](https://just.systems)
- [Poetry](https://python-poetry.org)
- Python 3.14

And bootstrap the local dev environment with:

```bash
just setup
```

This will setup locally a python virtualenv with all the dependencies, ready to start coding

