{"id":13509895,"url":"https://github.com/ggiamarchi/pxe-pilot","last_synced_at":"2025-04-30T09:10:55.316Z","repository":{"id":54610062,"uuid":"98520564","full_name":"ggiamarchi/pxe-pilot","owner":"ggiamarchi","description":"API and CLI to manage PXE configurations","archived":false,"fork":false,"pushed_at":"2020-11-05T08:43:58.000Z","size":753,"stargazers_count":73,"open_issues_count":6,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T14:41:38.689Z","etag":null,"topics":["baremetal","infrastructure-management","ipmi","pxe","pxe-boot","pxe-server","pxeboot","pxelinux"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ggiamarchi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-27T09:50:20.000Z","updated_at":"2024-10-30T21:16:08.000Z","dependencies_parsed_at":"2022-08-13T21:30:37.430Z","dependency_job_id":null,"html_url":"https://github.com/ggiamarchi/pxe-pilot","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggiamarchi%2Fpxe-pilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggiamarchi%2Fpxe-pilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggiamarchi%2Fpxe-pilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggiamarchi%2Fpxe-pilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ggiamarchi","download_url":"https://codeload.github.com/ggiamarchi/pxe-pilot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251674577,"owners_count":21625644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baremetal","infrastructure-management","ipmi","pxe","pxe-boot","pxe-server","pxeboot","pxelinux"],"created_at":"2024-08-01T02:01:16.261Z","updated_at":"2025-04-30T09:10:55.295Z","avatar_url":"https://github.com/ggiamarchi.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"# PXE Pilot\n\n[![Build Status](https://api.travis-ci.org/ggiamarchi/pxe-pilot.png?branch=master)](https://travis-ci.org/ggiamarchi/pxe-pilot)\n\nPXE Pilot helps you to manage PXE configurations for your hosts through a simple API. His role is very simple, it allows you to:\n\n- Know which configuration is associated with each host\n- To switch from a configuration to another one for a specific host\n\nThe REST API can be called either directly or using the CLI.\n\n# Why this software ?\n\nSome other software like Foreman or Cobbler can be used to manage PXE configurations in a more\nsofisticated way. For small deployments where only very basics features are needed, installing\nsuch a solution can appear overkill. In this situation, PXE Pilot could be what you need.\n\nSee also [the use case](USECASE.md) that leads me to create this project.\n\n# How does it work ?\n\nPXE pilot knows your hosts (with their MAC addresses) and your PXE configurations (see the\n\"configuration\" section)\n\nIt's important to understand that PXE Pilot does not help you to write PXE configurations. PXE Pilot\nbasically manages symlinks at the filesystem level to ensure each host uses the right configuration.\n\nWhen a host have several MAC addresses, the first address in the list points to the desired configuration\nand all the others point to the first one. This is to ensure the host will boot on the right configuration\nwhatever the network interface is used to boot.\n\n# Prerequisites\n\nUsing PXE Pilot suppose you already have a PXE server (DHCP + TFTP) up and running. PXE Pilot is DHCP\nand TFTP agnostic. It only work at the filesystem level into the TFTP root directory.\n\n# Running PXE Pilot\n\n## Configuration\n\nPXE Pilot needs to know three things:\n\n- The host list to manage\n- The absolute path to the TFTP root\n- The directory containing PXE configurations\n\nAll those information are described in the YAML file `/etc/pxe-pilot/pxe-pilot.yml`.\n\nOptionnaly, IPMI MAC address (or IP address) and credentials can be specified. When IPMI is available,\nPXE Pilot client shows power state for each host.\n\n__Example:__\n\n```yaml\n---\n\nhosts:\n  - name: h1\n    mac_addresses: [\"00:00:00:00:00:01\"]\n  - name: h2\n    mac_addresses: [\"00:00:00:00:00:02\"]\n    ipmi:\n      mac_address: \"00:00:00:00:00:a2\"\n      username: \"user\"\n      password: \"pass\"\n      interface: \"lanplus\"\n      subnets: \"10.0.0.0/24\"\n  - name: h3\n    mac_addresses: [\"00:00:00:00:00:03\", \"00:00:00:00:00:33\"]\n\ntftp:\n  root: \"/var/tftp\"\n\nconfiguration:\n  directory: /var/tftp/pxelinux.cfg/conf\n\nserver:\n  port: 3478\n```\n\n## Running PXE Pilot server\n\nBasically run\n\n```\n$ pxe-pilot server\n```\n\n## Querying PXE Pilot using the CLI\n\n```\n$ pxe-pilot --help\n\nUsage: pxe-pilot [OPTIONS] COMMAND [arg...]\n\nPXE Pilot\n\nOptions:\n  -s, --server=\"http://localhost:3478\"   Server URL for PXE Pilot client\n  -d, --debug=false                      Show client logs on stdout\n\nCommands:\n  server       Run PXE Pilot server\n  config       PXE configuration commands\n  host         Host commands\n\nRun 'pxe-pilot COMMAND --help' for more information on a command.\n```\n\nTh following examples assume PXE Pilot server is listening on `localhost:3478`. If not,\nuse the `--server` option to address your PXE Pilot server.\n\n### List available configurations\n\n```\n$ pxe-pilot config list\n\n+--------------+\n|     NAME     |\n+--------------+\n| local        |\n| ubuntu-14.04 |\n| ubuntu-16.04 |\n+--------------+\n```\n\n### List hosts\n\n```\n$ pxe-pilot host list\n\n+------+---------------+---------------------------------------+-------------------+-----------+-------------+\n| NAME | CONFIGURATION |             MAC ADDRESSES             |    IPMI MAC       | IPMI HOST | POWER STATE |\n+------+---------------+---------------------------------------+-------------------+-----------+-------------+\n| h1   | local         | 00:00:00:00:00:01                     |                   |           |             |\n| h2   |               | 00:00:00:00:00:02                     | 00:00:00:00:00:a2 | 1.2.3.4   | On          |\n| h3   | local         | 00:00:00:00:00:03 | 00:00:00:00:00:33 |                   |           |             |\n+------+---------------+---------------------------------------+-------------------+-----------+-------------+\n```\n\n### Deploy configuration for host(s)\n\nDeploy `ubuntu-16.04` configuration for hosts `h2`and `h3`.\n\n```\n$ pxe-pilot config deploy ubuntu-16.04 h2 h3\n\n+------+---------------+\n| NAME | CONFIGURATION |\n+------+---------------+\n| h2   | ubuntu-16.04  |\n| h3   | ubuntu-16.04  |\n+------+---------------+\n```\n\n# API Documentation\n\n## Read configurations\n\n```\nGET /v1/configurations\n```\n\n###### Response\n\n```json\n{\n    \"configurations\": [\n        {\n            \"name\": \"ubuntu-16.04\"\n        },\n        {\n            \"name\": \"local\"\n        },\n        {\n            \"name\": \"grml-2017.05\"\n        }\n    ]\n}\n```\n\n###### Response codes\n\nCode   | Name        | Description\n-------|-------------|---------------------------------------------------\n`20O`  | `Ok`        | Server configurations have been retrieved\n\n## Show configurations\n\n```\nGET /v1/configurations/\u003cname\u003e\n```\n\n###### Response\n\n```json\n{\n  \"name\": \"local\",\n  \"content\": \"default local\\n\\nlabel local\\n    localboot 0\\n\"\n}\n```\n\n###### Response codes\n\nCode   | Name        | Description\n-------|-------------|---------------------------------------------------\n`20O`  | `Ok`        | Configuration detail have been retrieved\n\n## Read hosts\n\n```\nGET /v1/hosts\n```\n\n###### Response\n\n```json\n[\n    {\n        \"name\": \"h1\",\n        \"macAddresses\": [\n            \"00:00:00:00:00:01\"\n        ],\n        \"configuration\": null\n    },\n    {\n        \"name\": \"h2\",\n        \"macAddresses\": [\n            \"00:00:00:00:00:02\"\n        ],\n        \"configuration\": {\n            \"name\": \"ubuntu-16.04\"\n        }\n    },\n    {\n        \"name\": \"h3\",\n        \"macAddresses\": [\n            \"00:00:00:00:00:03\",\n            \"00:00:00:00:00:33\"\n        ],\n        \"configuration\": {\n            \"name\": \"local\"\n        }\n    }\n]\n```\n\n###### Response codes\n\nCode   | Name          | Description\n-------|---------------|---------------------------------------------------\n`20O`  | `Ok`          | Host list had been retrieved\n\n\n## Reboot a host\n\n```\nPATCH /v1/hosts/\u003cname\u003e/reboot\n```\n\n###### Response codes\n\nCode   | Name          | Description\n-------|---------------|---------------------------------------------------\n`204`  | `No Content`  | Host had been successfully rebooted\n`404`  | `Not Found`   | Host does not exist\n`409`  | `Conflict`    | Reboot did not succeed for any reason\n\n\n## Deploy a configuration for host(s)\n\n```\nPUT /v1/configurations/\u003cconfiguration_name\u003e/deploy\n```\n\n###### Body\n\n```json\n{\n    \"hosts\": [\n        {\n            \"name\": \"h1\"\n        },\n        {\n            \"name\": \"h2\"\n        },\n        {\n            \"mac_address\": \"83:06:0a:00:cf:03\"\n        }\n    ]\n}\n```\n\n###### Error response (code 4xx)\n\n```json\n{\n    \"message\": \"Configuration not found\"\n}\n```\n\n###### Parameters\n\nName           | In    | Type     | Required | Description\n---------------|-------|----------|----------|-----------------------------------\n`hosts`        | body  | Host[]   | Yes      | Hosts for whom to deploy configuration\n\n###### Host (object)\n\nAttribute      | Type     | Required | Description\n---------------|----------|----------|---------------------------------------------\n`name`         | string   | No       | Host name\n`mac_address`  | string   | No       | Host MAC address\n`reboot`       | bool     | No       | Whether the host should be rebooted automatically or not\n\n\n###### Response codes\n\nCode   | Name          | Description\n-------|---------------|---------------------------------------------------\n`204`  | `No Content`  | Configurations had been deployed\n`404`  | `Not found`   | Either the configuation or a host is not found\n`400`  | `Bad request` | Malformed body\n\n\n## Refresh hosts information\n\nThis API populate the ARP table for all subnets in the PXE Pilot configuration\n\n```\nPATCH /v1/refresh\n```\n\n###### Response codes\n\nCode   | Name          | Description\n-------|---------------|---------------------------------------------------\n`204`  | `No Content`  | Refresh operation completed without any issue\n\n\n# License\n\nEverything in this repository is published under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggiamarchi%2Fpxe-pilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fggiamarchi%2Fpxe-pilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggiamarchi%2Fpxe-pilot/lists"}