- Notifications
You must be signed in to change notification settings - Fork9
API and CLI to manage PXE configurations
License
ggiamarchi/pxe-pilot
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
PXE Pilot helps you to manage PXE configurations for your hosts through a simple API. His role is very simple, it allows you to:
- Know which configuration is associated with each host
- To switch from a configuration to another one for a specific host
The REST API can be called either directly or using the CLI.
Some other software like Foreman or Cobbler can be used to manage PXE configurations in a moresofisticated way. For small deployments where only very basics features are needed, installingsuch a solution can appear overkill. In this situation, PXE Pilot could be what you need.
See alsothe use case that leads me to create this project.
PXE pilot knows your hosts (with their MAC addresses) and your PXE configurations (see the"configuration" section)
It's important to understand that PXE Pilot does not help you to write PXE configurations. PXE Pilotbasically manages symlinks at the filesystem level to ensure each host uses the right configuration.
When a host have several MAC addresses, the first address in the list points to the desired configurationand all the others point to the first one. This is to ensure the host will boot on the right configurationwhatever the network interface is used to boot.
Using PXE Pilot suppose you already have a PXE server (DHCP + TFTP) up and running. PXE Pilot is DHCPand TFTP agnostic. It only work at the filesystem level into the TFTP root directory.
PXE Pilot needs to know three things:
- The host list to manage
- The absolute path to the TFTP root
- The directory containing PXE configurations
All those information are described in the YAML file/etc/pxe-pilot/pxe-pilot.yml.
Optionnaly, IPMI MAC address (or IP address) and credentials can be specified. When IPMI is available,PXE Pilot client shows power state for each host.
Example:
---hosts: -name:h1mac_addresses:["00:00:00:00:00:01"] -name:h2mac_addresses:["00:00:00:00:00:02"]ipmi:mac_address:"00:00:00:00:00:a2"username:"user"password:"pass"interface:"lanplus"subnets:"10.0.0.0/24" -name:h3mac_addresses:["00:00:00:00:00:03", "00:00:00:00:00:33"]tftp:root:"/var/tftp"configuration:directory:/var/tftp/pxelinux.cfg/confserver:port:3478
Basically run
$ pxe-pilot server$ pxe-pilot --helpUsage: pxe-pilot [OPTIONS] COMMAND [arg...]PXE PilotOptions: -s, --server="http://localhost:3478" Server URL for PXE Pilot client -d, --debug=false Show client logs on stdoutCommands: server Run PXE Pilot server config PXE configuration commands host Host commandsRun 'pxe-pilot COMMAND --help' for more information on a command.Th following examples assume PXE Pilot server is listening onlocalhost:3478. If not,use the--server option to address your PXE Pilot server.
$ pxe-pilot config list+--------------+| NAME |+--------------+| local || ubuntu-14.04 || ubuntu-16.04 |+--------------+$ pxe-pilot host list+------+---------------+---------------------------------------+-------------------+-----------+-------------+| NAME | CONFIGURATION | MAC ADDRESSES | IPMI MAC | IPMI HOST | POWER STATE |+------+---------------+---------------------------------------+-------------------+-----------+-------------+| h1 | local | 00:00:00:00:00:01 | | | || h2 | | 00:00:00:00:00:02 | 00:00:00:00:00:a2 | 1.2.3.4 | On || h3 | local | 00:00:00:00:00:03 | 00:00:00:00:00:33 | | | |+------+---------------+---------------------------------------+-------------------+-----------+-------------+Deployubuntu-16.04 configuration for hostsh2andh3.
$ pxe-pilot config deploy ubuntu-16.04 h2 h3+------+---------------+| NAME | CONFIGURATION |+------+---------------+| h2 | ubuntu-16.04 || h3 | ubuntu-16.04 |+------+---------------+GET /v1/configurations{"configurations": [ {"name":"ubuntu-16.04" }, {"name":"local" }, {"name":"grml-2017.05" } ]}| Code | Name | Description |
|---|---|---|
20O | Ok | Server configurations have been retrieved |
GET /v1/configurations/<name>{"name":"local","content":"default local\n\nlabel local\n localboot 0\n"}| Code | Name | Description |
|---|---|---|
20O | Ok | Configuration detail have been retrieved |
GET /v1/hosts[ {"name":"h1","macAddresses": ["00:00:00:00:00:01" ],"configuration":null }, {"name":"h2","macAddresses": ["00:00:00:00:00:02" ],"configuration": {"name":"ubuntu-16.04" } }, {"name":"h3","macAddresses": ["00:00:00:00:00:03","00:00:00:00:00:33" ],"configuration": {"name":"local" } }]| Code | Name | Description |
|---|---|---|
20O | Ok | Host list had been retrieved |
PATCH /v1/hosts/<name>/reboot| Code | Name | Description |
|---|---|---|
204 | No Content | Host had been successfully rebooted |
404 | Not Found | Host does not exist |
409 | Conflict | Reboot did not succeed for any reason |
PUT /v1/configurations/<configuration_name>/deploy{"hosts": [ {"name":"h1" }, {"name":"h2" }, {"mac_address":"83:06:0a:00:cf:03" } ]}{"message":"Configuration not found"}| Name | In | Type | Required | Description |
|---|---|---|---|---|
hosts | body | Host[] | Yes | Hosts for whom to deploy configuration |
| Attribute | Type | Required | Description |
|---|---|---|---|
name | string | No | Host name |
mac_address | string | No | Host MAC address |
reboot | bool | No | Whether the host should be rebooted automatically or not |
| Code | Name | Description |
|---|---|---|
204 | No Content | Configurations had been deployed |
404 | Not found | Either the configuation or a host is not found |
400 | Bad request | Malformed body |
This API populate the ARP table for all subnets in the PXE Pilot configuration
PATCH /v1/refresh| Code | Name | Description |
|---|---|---|
204 | No Content | Refresh operation completed without any issue |
Everything in this repository is published under the MIT license.
About
API and CLI to manage PXE configurations