philpagel / debian-headless

Debian headless/remote installation Installing Debian is easy enough – but what if you have no physical access to the target machine or it has no screen or keyboard? Stock images require at least a few local key strokes before you can continue the installation, remotely... This little tool will remaster a stock Debian image for 100% remote installation via ssh or serial console. In a nutshell # Edit the configuration variables make config # download the latest Debian netinst image make download # Adapt preseed.cfg edit preseed.cfg # Build image make image # Write image to usb stick make usb Motivation I wanted to install Debian on a server remotely – i.e. without keyboard access or the chance to peek at a physical screen. I found plenty of information on the net but none of the tutorials really worked for me. Some included preseeding the image but failed to automatically start the installation without a key press, others seemed to customize a zillion things but ended up getting stuck in some error message or other. The problem with ssh remote installation with stock images is that they still require some initial human interaction to select the desired menu option and some basic setup before the network is configured. That makes the whole point of remote installation moot... So I read my way through lots of tutorials and put together a slim working solution – at least working for me. So here is my minimal and lazy solution to Debian headless installation image building. I mostly documented it for myself but maybe it's useful for someone out there. My main intent was to connect to the ssh-server of the Debian installer. Another possible route for headless installation is via serial console. That can either be a physical RS-232 cable or a virtual serial port provided by a remote management module/software such as HPEs iLO or something similar. Known quirks and issues The Makefile we use here to implement all functionality intentionally lacks some of the typical Make magic: Targets don't track dependencies so you will have to rebuild everything, whenever you change something. So please , first. Yes – a full build will cost you a valuable six seconds every time. Use them to worship code simplicity. I didn't have much luck with booting i386 images via UEFI – neither the stock Debian images nor the remastered ones. But maybe it's just my particular machine/BIOS... Dependencies To install all necessary tools run: make install-depends This tool was developed and tested on Debian LINUX. While all major LINUX distributions are likely to offer the necessary pieces of software, there may be some non-obvious differences. Accordingly, I recommend to run this on a Debian system. One difference that I am aware of is that many distributions use either or and make one of them a symbolic link to the other. In this particular case, they are not interchangeable – is required. If you don't have a Debian system, you can build using a docker container – see below Configuration Edit and set the variables to match your situation. You can use make config to do so. This should work on most Debian-based systems. If it doesn't, just edit the file with your preferred text editor. Image names, architecture and usb device At the very minimum you need to set the following variables: : the name of your stock Debian ISO image file. the name of the remastered ISO image. (DEPRECATED) indicates the target processor architecture – or (other architectures are not supported). This variable is used to identify the installation folder in the image ( ) and to determine which image to download. As of Debian 13, is no longer a supported architecture. For the moment, I will keep the variable to support working with legacy versions. In the long run this option will disappear. is the device file that represents your usb stick. The latter is needed for and . Be **extra careful** to set correctly! If you set it incorrectly, you may overwrite your system disk! is the CD volume label. It *must* be ≤ 32 chars in length. Console parameters While the main goal of this project was to allow installation via , a serial console is an alternative in some cases. The following default config for the serial console device should work most of the time: CONSOLE = ttyS0,115200n8 When the serial console is active, *all output* is redirected to the serial interface and you will not see boot messages or the installer on a connected screen after that point. Accordingly, normal local installation will not work. If you want your image to allow local installation (i.e. non-headless), instead, you may set CONSOLE = tty0 Download Debian installation image You can just download the latest Debian *netinst* image with make download If this is not the image you want to start with, just download/provide one yourself and save it in the folder where this Makefile lives. In any case, make sure to set the variable in the config file ( ) to match the image name. Preseeding Preseeding is Debian's method of automatically answering some or all of the configuration questions you usually have to answer during the installation process. You *must provide* a file for headless installation! The included file configures the bare minimum to get past the installer questions so that network and ssh can be launched. Please edit the file – at least change the password... If the minimal file does not cover all your needs, get a full template make example-preseed.cfg mv example-preseed.cfg preseed.cfg and modify it to your needs. For comprehensive information on preseeding, study this: or Building the ISO make clean make image Manual modifications to the image For experts, only! If you know what you are doing, you can now enter the folder and add packages, edit files etc. You can find some information on what you can do here. But you don't need to manually follow the steps for re-creating md5 sums and assembling…