deserializeme/pxeless repository overview

⁠What is PXEless?

It's an automated system install and image-creation tool for situations where provisioning machines via a PXE server is not an option, or is not an option yet. It's ideal for small-scale greenfielding, proofs-of-concept, and general management of on-prem compute infrastructure in a cloud-native way without the cloud.

PXEless is based on covertsh/ubuntu-autoinstall-generator⁠, and generates a customized Ubuntu auto-intstall ISO. This is accomplished by using cloud-init⁠ and Ubuntu's Ubiquity installer⁠ - specifically the server variant known as Subiquity⁠, which itself wraps Curtin⁠.

PXEless works by:

1. Downloading the ISO of your choice - a daily build, or a release.
2. Extracting the EFI, MBR, and File-System from the ISO
3. Adding some kernel command line parameters
4. Adding customised autoinstall and cloud-init configuration files
5. Copying arbitrary files to / running scripts against the squashfs (Optional)
6. Repacking the data into a new ISO.

The resulting product is a fully-automated Ubuntu installer. This serves as an easy stepping-off point for configuration-management tooling like Ansible, Puppet, and Chef or personalization tools like jessebot/onboardme⁠. Please note that while similar in schema, the Autoinstall and Cloud-Init portions of the user-data file do not mix. The user-data key marks the transition from autoinstall to cloud-init syntax as seen HERE⁠

⁠Application Flow

⁠Docker Quickstart

It is advised to run PXEless in a docker container due to it's reliance on Linux-only packages.

1. Clone the rpos

   git clone https://github.com/cloudymax/pxeless.git
   

   Copy

2. Change directory to the root of the repo

   cd pxeless
   

   Copy

3. Run in a Docker container:

   • Basic Usage:

     docker run --rm --volume "$(pwd):/data" \
       --user $(id -u):$(id -g) deserializeme/pxeless \
       --all-in-one  \
       --user-data user-data.basic \
       --code-name jammy \
       --use-release-iso 
     

     Copy

   • Adding static files to the ISO

     Take note that we do not specify a user here. Adding extra files to the ISO via the -x or --extra-files flag requires root access in order to chroot the squashfs.

     The contents of the extras directory will be copied to the /media dir of the image's filesystem. The extra-files are mounted as /data/<directory> when running in a docker conatiner because we mount $(pwd) as /data/

     docker run --rm --volume "$(pwd):/data" deserializeme/pxeless \
       --all-in-one \
       --user-data user-data.basic \
       --code-name jammy \
       --use-release-iso \
       --extra-files /data/extras
     

     Copy

   • Offline Installation

     Running an offline installer script to customize image during build procedure. Adding a bash script as content of the extras directory. The script should be passed to image-create using -o or --offline-installer.

        docker run --rm --volume "$(pwd):/data" deserializeme/pxeless \
         --all-in-one \
         --user-data user-data.basic \
         --code-name jammy \
         --use-release-iso \
         --extra-files /data/extras \
         --offline-installer installer-sample.sh
     

     Copy

4. Writing your ISO to a USB drive

   • On MacOS I reccommend using Etcher⁠

   • On Linux use dd.

     # /dev/sdb is assumed for the sake of the example
     
     export IMAGE_FILE="ubuntu-autoinstall.iso"
     
     sudo fdisk -l |grep "Disk /dev/"
     
     export DISK_NAME="/dev/sdb"
     
     sudo umount "$DISK_NAME"
     
     sudo dd bs=4M if=$IMAGE_FILE of="$DISK_NAME" status=progress oflag=sync
     

     Copy

5. Boot your ISO file on a physical machine for VM and log-in. If you used my user-data.basic file the user is vmadmin, and the password is password. You can create your own credentials by running mkpasswd --method=SHA-512 --rounds=4096 as documented on THIS⁠ page at line 49.

⁠Command-line options

⁠Sources

This project is made possible through the open-source work of the following authors and many others. Thank you all for sharing your time, effort, and knowledge freely with us. You are the giants upon whos shoulders we stand. :heart:

⁠Need something different?

PXEless currently only supports creating ISO's using Ubuntu Server (Focal and Jammy). Users who's needs ae not met by PXEless may find these other FOSS projects useful:

⁠Testing your ISO with QEMU

    sudo apt-get install -y qemu-kvm \
        bridge-utils \
        virtinst\
        ovmf \
        qemu-utils \
        cloud-image-utils \
        ubuntu-drivers-common \
        whois \
        git \
        guestfs-tools

⁠Contributors

Max! ⁠	Lars Munch ⁠	Meraj Kashi ⁠	Koen Van De Sande ⁠	Snyk Bot ⁠	Markus Pöschl ⁠
Arnold ⁠	N0k0m3 ⁠	MrKinauJr ⁠	Toro ⁠	Webber Takken ⁠	Null ⁠

⁠License

MIT license.

This spin-off project adds support for eltorito + GPT images required for Ubuntu 20.10 and newer⁠. It also keeps support for the now depricated isolinux + MBR⁠ image type. In addition, the process is dockerized to make it possible to run on Mac/Windows hosts in addition to Linux. Automated builds via github actions have also been created.