From 75199db0ebf57024ff5d5b8cc7730bcfa38e3d51 Mon Sep 17 00:00:00 2001 From: Adam Rozman Date: Thu, 28 Sep 2023 12:34:34 +0300 Subject: [PATCH] add initial commit This commit establishes the ipxe-builder repositroy. The goal of this repository is to: - Provide the ability to build an OCI container that: - Provides customizable custom IPXE firmware building functionality. - Ability to either build IPXE firmware from an already existing cash. - Abiltiy to pull IPXE firmware source code and build the firmware based on that. - Embed custom IPXE script in the firmware. - Enable IPV6 or TLS 1.3 support for the firmware. - Provide documentations (README) about usage of the ipxe-builder container. - Add OWNERS file - Add security contacts file - Add licence Signed-off-by: Adam Rozman --- LICENSE | 201 +++++++++++++++++++++++++++++++++++++ OWNERS | 15 +++ README.md | 60 +++++++++++ SECURITY_CONTACTS | 11 ++ ipxe-builder/Dockerfile | 7 ++ ipxe-builder/buildipxe | 99 ++++++++++++++++++ ipxe-builder/embed.ipxe.j2 | 14 +++ 7 files changed, 407 insertions(+) create mode 100644 LICENSE create mode 100644 OWNERS create mode 100644 README.md create mode 100644 SECURITY_CONTACTS create mode 100644 ipxe-builder/Dockerfile create mode 100755 ipxe-builder/buildipxe create mode 100644 ipxe-builder/embed.ipxe.j2 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/OWNERS b/OWNERS new file mode 100644 index 0000000..67ffdbd --- /dev/null +++ b/OWNERS @@ -0,0 +1,15 @@ +# See the OWNERS docs at https://go.k8s.io/owners + +approvers: + - Rozzi + - lentzi90 + +reviewers: + - mboukhalfa + - kashifest + - dtantsur + - elfosardo + +emeritus_reviewers: + +emeritus_approvers: diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f654c1 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# Metal3 iPXE builder container + +## Description + +This repository provides the ability to build an OCI container that: + - Provides customizable custom IPXE firmware building functionality. + - Ability to either build IPXE firmware from an already existing cash. + - Ability to pull IPXE firmware source code and build the firmware based + on that. + - Embed custom IPXE script in the firmware. + - Enable IPV6 or TLS 1.3 support for the firmware. + +## External runtime dependencies + +- In order to build the iPXE firmware with TLS support, the user needs to +provide relevant certificate and certificate key files e.g. via a mounted +volume. + +- If the ipxe-builder is instructed to build from existing iPXE source code +cache, then the cahce has to be provided e.g. via a mounted volume. + +- In order to get a usable output the user needs to mount a directory +where the iPXE builder script can put the build outputs. + +Expected paths to the external runtime dependencies can be configured +via run-time environment variables. + +## Configuration + +The following environment variables can be passed in to customize run-time +functionality: + +- BUILD_FROM_CACHE` - specifies whether the ipxebuilder should build + the firmware from a local directory or not. (default `true`) +- `IPXE_BUILD_FROM_REPO` specifies whether the ipxebuilder should build + from a remote git repo. (default `false`) +- `IPXE_SHARED_FIRMWARE_SOURCE` path to the iPXE source directory + (default `/shared/ipxe-source`) +- `IPXE_EMBED_SCRIPT` path to the iPXE script that will be embedded in the + custom iPXE firmware built by `the ipxebuilder`. (default `/bin/embed.ipxe`) +- `IPXE_EMBED_SCRIPT_TEMPLATE` path to the jinja template of the iPXE script + that will be embedded in the custom firmware built by the ipxebuilder. This + template is rendered in runtime by the builder script + (default `/bin/embed.ipxe.j2`) +- `IPXE_RELEASE_BRANCH` the iPXE source code should be pulled from this branch + , only relevant when `IPXE_BUILD_FROM_REPO` is `true` (default `v1.21.1`) +- `IPXE_ENABLE_IPV6` build the iPXE firmware with IPV6 support enabled `false` +- `IPXE_ENABLE_HTTPS` build the iPXE firmware with TLS support enabled `false` +- `IPXE_CUSTOM_FIRMWARE_DIR` output location for the build process + (default: `/shared/custom_ipxe_firmware`) +- `IPXE_CERT_FILE` expected location of the TLS certificate used during build + (default: `/certs/ipxe/tls.crt`) +- `IPXE_KEY_FILE` expected location of the TLS key used during build + (default: `/certs/ipxe/tls.key`) +- `IPXE_TLS_PORT` this port will be used to start chainloading by a TLS enabled + iPXE firmware, this value is used to render the embed.ipxe.j2 script template + (default: `8084`) +- `IPXE_CHAIN_HOST` this ip will be used to start chainloading by a TLS enabled + iPXE firmware, this value is used to render the embed.ipxe.j2 script template + (default: `0.0.0.0`) diff --git a/SECURITY_CONTACTS b/SECURITY_CONTACTS new file mode 100644 index 0000000..c29a9e6 --- /dev/null +++ b/SECURITY_CONTACTS @@ -0,0 +1,11 @@ +# Reporting a security vulnerability + +Please do: + - not disclose any security issue publicly e.g. Pull Requests, Comments. + - not disclose any security issue directly to any owner of the repository or + to any other contributor. + +In this repository security reports are handled according to the +Metal3-io project's security policy. For more information about the security +policy consult the User-Guide [here](https://book.metal3.io/security_policy.html). + diff --git a/ipxe-builder/Dockerfile b/ipxe-builder/Dockerfile new file mode 100644 index 0000000..1d67174 --- /dev/null +++ b/ipxe-builder/Dockerfile @@ -0,0 +1,7 @@ +FROM quay.io/centos/centos:stream9 + +RUN dnf install -y gcc git-core make perl xz-devel python3-setuptools python3-jinja2 + +COPY buildipxe embed.ipxe.j2 /bin/ + +CMD /bin/buildipxe diff --git a/ipxe-builder/buildipxe b/ipxe-builder/buildipxe new file mode 100755 index 0000000..b045ba3 --- /dev/null +++ b/ipxe-builder/buildipxe @@ -0,0 +1,99 @@ +#!/usr/bin/bash + +set -euxo pipefail +# ENV VARIABLE CONFIG # + +# This script should be used as an init container's entry point thus +# it is expected that the user would like to build the ipxe when this script +# is started. By default the script will try to build from cache and fails +# if the cache is unavailable. +export IPXE_CUSTOM_FIRMWARE_DIR="${IPXE_CUSTOM_FIRMWARE_DIR:-/shared/custom_ipxe_firmware}" +export IPXE_BUILD_FROM_CACHE="${IPXE_BUILD_FROM_CACHE:-true}" +export IPXE_BUILD_FROM_REPO="${IPXE_BUILD_FROM_REPO:-false}" +export IPXE_SHARED_FIRMWARE_SOURCE="${IPXE_SHARED_FIRMWARE_SOURCE:-/shared/ipxe-source}" +export IPXE_EMBED_SCRIPT="${IPXE_EMBED_SCRIPT:-/bin/embed.ipxe}" +export IPXE_EMBED_SCRIPT_TEMPLATE="${IPXE_EMBED_SCRIPT_TEMPLATE:-/bin/embed.ipxe.j2}" +export IPXE_RELEASE_BRANCH="${IPXE_RELEASE_BRANCH:-v1.21.1}" +export IPXE_ENABLE_IPV6="${IPXE_ENABLE_IPV6:-false}" +export IPXE_ENABLE_HTTPS="${IPXE_ENABLE_TLS:-false}" +export IPXE_CERT_FILE="${IPXE_CERT_FILE:-/certs/ipxe/tls.crt}" +export IPXE_KEY_FILE="${IPXE_KEY_FILE:-/certs/ipxe/tls.key}" +export IPXE_TLS_PORT="${IPXE_TLS_PORT:-8084}" +export IPXE_CHAIN_HOST="${IPXE_CHAIN_HOST:-0.0.0.0}" +# IPXE_BUILD_OPTIONS are not configurable directly +export IPXE_BUILD_OPTIONS="NO_WERROR=1 EMBED=${IPXE_EMBED_SCRIPT}" +# PREPARE SOURCE # + +render_j2_config(){ + python3 -c 'import os; import sys; import jinja2; sys.stdout.write(jinja2.Template(sys.stdin.read()).render(env=os.environ))' < "$1" > "$2" +} + +# Create debug folder +mkdir -p "/shared/ipxe-debug" + +# In case building ipxe firmware from shared volume +if [[ "${IPXE_BUILD_FROM_CACHE}" == "true" ]]; then + if [[ -r "${IPXE_SHARED_FIRMWARE_SOURCE}" ]]; then + cp -r "${IPXE_SHARED_FIRMWARE_SOURCE}" "/tmp" + ls -all "/tmp/ipxe-source" + else + echo "ERROR: can't build ipxe from cache, there is no path!" >&2 + exit 1 + fi +# In case building ipxe firmware from upstream git repo directly +# Requires Internet access! +elif [[ "${IPXE_BUILD_FROM_CACHE}" != "true" ]] \ + && [[ "${IPXE_BUILD_FROM_REPO}" == "true" ]]; then + git clone --depth 1 --branch "${IPXE_RELEASE_BRANCH}" \ + "https://github.com/ipxe/ipxe.git" \ + "/tmp/ipxe-source" +# In case neither cache nor git repo based ipxe building is initiated, +# the script will fail with an error message! +elif [[ "${IPXE_BUILD_FROM_CACHE}" != "true" ]] \ + && [[ "${IPXE_BUILD_FROM_REPO}" != "true" ]]; then + echo "ERROR: neither IPXE_BUILD_FROM_REPO nor IPXE_BUILD_FROM_CACHE has the value: true!" >&2 + echo "ERROR: the ipxe build script has got no source specified, it will exit with an error!" >&2 + exit 1 +fi + +# Copying the source to the work directory has failed. +if [[ ! -r "/tmp/ipxe-source" ]]; then + echo "ERROR: the ipxe firmware source is missing from /tmp/ipxe-source!" >&2 + echo "ERROR: copying the source to the work directory has failed." >&2 + echo "ERROR: check the value of the IPXE_SHARED_FIRMWARE_SOURCE env variable!" >&2 + exit 1 +fi + +# BUILD # +ARCH=$(uname -m | sed 's/aarch/arm/') +# NOTE(elfosardo): warning should not be treated as errors by default +cd "/tmp/ipxe-source/src" +if [[ "${IPXE_ENABLE_IPV6}" == "true" ]]; then + sed -i 's/^\/\/#define[ \t]NET_PROTO_IPV6/#define\tNET_PROTO_IPV6/g' \ + "config/general.h" +fi +if [[ "${IPXE_ENABLE_TLS}" == "true" ]]; then + if [[ ! -r "${IPXE_CERT_FILE}" ]]; then + echo "ERROR: iPXE TLS support is enabled but cert is missing!" >&2 + exit 1 + fi + sed -i 's/^#define[ \t]DOWNLOAD_PROTO_HTTP/#undef\tDOWNLOAD_PROTO_HTTP/g' \ + "config/general.h" + sed -i 's/^#undef[ \t]DOWNLOAD_PROTO_HTTPS/#define\tDOWNLOAD_PROTO_HTTPS/g' \ + "config/general.h" + echo "IPXE BUILD OPTIONS ARE EXTENDED WITH CERTS!!!" + render_j2_config "${IPXE_EMBED_SCRIPT_TEMPLATE}" "${IPXE_EMBED_SCRIPT}" + export IPXE_BUILD_OPTIONS="${IPXE_BUILD_OPTIONS} CERT=${IPXE_CERT_FILE} TRUST=${IPXE_CERT_FILE}" +fi + +sed -i 's/^\/\/#define[ \t]CONSOLE_SERIAL/#define\tCONSOLE_SERIAL/g' \ + "config/console.h" + +/usr/bin/make "bin/undionly.kpxe" "bin-${ARCH}-efi/snponly.efi" ${IPXE_BUILD_OPTIONS[@]} + +mkdir -p "${IPXE_CUSTOM_FIRMWARE_DIR}" +# These files will be copied by the rundnsmasq script to the shared volume. +cp "/tmp/ipxe-source/src/bin/undionly.kpxe" \ + "/tmp/ipxe-source/src/bin-${ARCH}-efi/snponly.efi" \ + "${IPXE_CUSTOM_FIRMWARE_DIR}" + diff --git a/ipxe-builder/embed.ipxe.j2 b/ipxe-builder/embed.ipxe.j2 new file mode 100644 index 0000000..a8545b2 --- /dev/null +++ b/ipxe-builder/embed.ipxe.j2 @@ -0,0 +1,14 @@ +#!ipxe + +:chainload +echo Initiating DHCP based interface configuration +dhcp +echo Start chainloading https://{{ env.IPXE_CHAIN_HOST }}:{{ env.IPXE_TLS_PORT }}/boot.ipxe +chain https://{{ env.IPXE_CHAIN_HOST }}:{{ env.IPXE_TLS_PORT }}/boot.ipxe || goto boot_failed +echo Chainloading succeeded! + +:boot_failed +echo Chainloading failed! +echo Press any key to reboot... +prompt --timeout 60 +reboot