{"id":48391720,"url":"https://github.com/philpagel/debian-headless","last_synced_at":"2026-04-06T00:15:21.121Z","repository":{"id":37925588,"uuid":"150996787","full_name":"philpagel/debian-headless","owner":"philpagel","description":"Create a debian headless/remote installation image","archived":false,"fork":false,"pushed_at":"2026-03-17T12:05:23.000Z","size":172,"stargazers_count":239,"open_issues_count":2,"forks_count":36,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-03-18T02:47:10.203Z","etag":null,"topics":["boot","debian"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philpagel.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-09-30T18:58:28.000Z","updated_at":"2026-03-17T12:05:27.000Z","dependencies_parsed_at":"2025-01-17T20:26:08.139Z","dependency_job_id":"2ed52c2c-7a44-4fae-b64f-c01b3bcb3057","html_url":"https://github.com/philpagel/debian-headless","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/philpagel/debian-headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philpagel%2Fdebian-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philpagel%2Fdebian-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philpagel%2Fdebian-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philpagel%2Fdebian-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philpagel","download_url":"https://codeload.github.com/philpagel/debian-headless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philpagel%2Fdebian-headless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31454272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"ssl_error","status_checked_at":"2026-04-05T21:22:51.943Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["boot","debian"],"created_at":"2026-04-06T00:15:20.585Z","updated_at":"2026-04-06T00:15:21.109Z","avatar_url":"https://github.com/philpagel.png","language":"Makefile","readme":"# Debian headless/remote installation\n\nInstalling Debian is easy enough – but what if you have no physical access to\nthe target machine or it has no screen or keyboard? Stock images require at\nleast a few local key strokes before you can continue the installation,\nremotely...\n\nThis little tool will remaster a stock Debian image for 100% remote installation\nvia ssh or serial console.\n\n## In a nutshell\n    \n    # Edit the configuration variables\n    make config\n\n    # download the latest Debian netinst image\n    make download\n\n    # Adapt preseed.cfg\n    edit preseed.cfg\n\n    # Build image\n    make image\n\n    # Write image to usb stick\n    make usb\n\n\n## Motivation\n\nI wanted to install Debian on a server remotely – i.e. without keyboard access\nor the chance to peek at a physical screen. I found plenty of information on\nthe net but none of the tutorials really worked for me. Some included\npreseeding the image but failed to automatically start the installation without\na key press, others seemed to customize a zillion things but ended up getting\nstuck in some error message or other.  The problem with ssh remote installation\nwith stock images is that they still require some initial human interaction to\nselect the desired menu option and some basic setup before the network is\nconfigured. That makes the whole point of remote installation moot...\n\nSo I read my way through lots of tutorials and put together a slim working\nsolution – at least working for me. So here is my minimal and lazy solution to\nDebian headless installation image building.  I mostly documented it for myself\nbut maybe it's useful for someone out there.\n\nMy main intent was to connect to the ssh-server of the Debian installer.\nAnother possible route for headless installation is via serial console. That\ncan either be a physical RS-232 cable or a virtual serial port provided by a\nremote management module/software such as HPEs iLO or something similar.\n\n## Known quirks and issues\n\nThe Makefile we use here to implement all functionality intentionally lacks\nsome of the typical Make magic: Targets don't track dependencies so you will\nhave to rebuild everything, whenever you change something. So please `make\nclean`, first. Yes – a full build will cost you a valuable six seconds every\ntime. Use them to worship code simplicity.\n\nI didn't have much luck with booting i386 images via UEFI – neither the stock\nDebian images nor the remastered ones. But maybe it's just my particular\nmachine/BIOS...\n\n\n## Dependencies\n\nTo install all necessary tools run:\n\n    make install-depends\n\nThis tool was developed and tested on Debian LINUX. While all major LINUX\ndistributions are likely to offer the necessary pieces of software, there may\nbe some non-obvious differences. Accordingly, I recommend to run this on a\nDebian system. One difference that I am aware of is that many distributions use\neither `genisoimage` or `mkisofs` and make one of them a symbolic link to the\nother. In this particular case, they are not interchangeable – `genisoimage`\nis required.\n\nIf you don't have a Debian system, you can build using a docker container –\nsee [below](#building-in-a-non-debian-environment)\n\n\n## Configuration\n\nEdit `Makevars` and set the variables to match your situation. You can use \n\n    make config\n\nto do so. This should work on most Debian-based systems. If it doesn't, just edit\nthe `Makevars` file with your preferred text editor.\n\n\n### Image names, architecture and usb device\n\nAt the very minimum you need to set the following variables:\n\n`SOURCE`: the name of your stock Debian ISO image file.\n\n`TARGET` the name of the remastered ISO image.\n\n`ARCH` (DEPRECATED) indicates the target processor architecture – `amd64` or\n`i386` (other architectures are not supported). This variable is used to\nidentify the installation folder in the image (`install.amd`) and to determine\nwhich image to download. As of Debian 13, `i386` is no longer a supported\narchitecture.  For the moment, I will keep the variable to support working with\nlegacy versions. In the long run this option will disappear.\n\n`USBDEV` is the device file that represents your usb stick. The latter is\nneeded for `make usb` and `make FAT`. Be **extra careful** to set `USBDEV`\ncorrectly! If you set it incorrectly, you may overwrite your system disk!\n\n`LABEL` is the CD volume label. It *must* be ≤ 32 chars in length.\n\n\n\n### Console parameters\n\nWhile the main goal of this project was to allow installation via `ssh`, a serial \nconsole is an alternative in some cases.\n\nThe following default config for the serial console device should work most of\nthe time:\n\n    CONSOLE = ttyS0,115200n8\n\nWhen the serial console is active, *all output* is redirected to the serial\ninterface and you will not see boot messages or the installer on a connected\nscreen after that point. Accordingly, normal local installation will not work.\nIf you want your image to allow local installation (i.e. non-headless),\ninstead, you may set\n\n    CONSOLE = tty0\n\n\n\n## Download Debian installation image\n\nYou can just download the latest Debian *netinst* image with\n\n    make download\n\nIf this is not the image you want to start with, just download/provide one\nyourself and save it in the folder where this Makefile lives.  \n\nIn any case, make sure to set the `SOURCE` variable in the config file (`make\nconfig`) to match the image name.\n\n\n\n## Preseeding\n\nPreseeding is Debian's method of automatically answering some or all of the\nconfiguration questions you usually have to answer during the installation\nprocess.\n\nYou *must provide* a `preseed.cfg` file for headless installation!\n\nThe included `preseed.cfg` file configures the bare minimum to get past the\ninstaller questions so that network and ssh can be launched.  Please edit the\nfile – at least change the password...\n\nIf the minimal file does not cover all your needs, get a full template\n\n    make example-preseed.cfg\n    mv example-preseed.cfg preseed.cfg\n\nand modify it to your needs. For comprehensive information on preseeding, study\nthis:\n\n\u003chttps://www.debian.org/releases/stable/amd64/apb.en.html\u003e\n\nor\n\n\u003chttps://www.debian.org/releases/stable/i386/apb.en.html\u003e\n\n\n## Building the ISO\n\n    make clean\n    make image\n\n\n## Manual modifications to the image\n\nFor experts, only! If you know what you are doing, you can now enter the `tmp`\nfolder and add packages, edit files etc. You can find some information on what\nyou can do [here](https://wiki.debian.org/DebianInstaller/Modify/CD). But you\ndon't need to manually follow the steps for re-creating md5 sums and assembling\nthe image.\n\nTo pack your changes into the image just run the last steps manually, again:\n\n    make md5sums\n    make iso\n\n\n## Dry run it\n\nThis step is optional but may save you a lot of trouble later.\n\n    make qemu-bios\n    make qemu-uefi\n\nThis will fire up a QEMU session booting your new image.\n\n\nYou can follow the\nboot process in the emulator and eventually connect to the installer like this:\n\n    ssh installer@localhost -p22222\n\nOr via serial console:\n\n    telnet localhost 33333\n\nSo you can test-drive the installation before trying it on a real server.  The\ndefault password is `r00tme` – please change it in the preseeding file.\nAlternatively, you can configure passwordless login via ssh key file – there\nis example code in the `preseed.cfg`. For this to work, you need to provide the\nkey file from a local web server. In pinch, this may be all you need:\n\n    python3 -m http.server\n\nAnd here a little screenshot of what that looks like in qemu. The two bottom\npanels show the local screen (left) and the serial console (right):\n\n![](screenshot.png)\n\n\n## Write to usb stick or burn cd\n\nIf you still have a cdrom drive, use your favorite ISO burner to write the\nimage to cd. I can't find my old usb-cd drive and prefer using a usb stick,\nanyway:\n\nInsert a USB stick and find out its device file\n\n    lsblk\n\n**Double check**, that `USBDEV` is set correctly in `Makevars`.\n\n**Caution:** The next two steps will write to the device configured in the\n`USBDEV`. If you failed to set that correctly, you will overwrite whatever disk\nhappens to be associated with that device!\n\nWrite the image to the stick:\n\n    make usb\n\nAdd a FAT partition to the stick:\n\n    make FAT\n\nThis may be useful if you need to add custom firmware files or anything else\nyou would like to use during installation.\n\n\n## Building in a non-Debian environment\n\nThe build process works on Debian machines. However, some users want to install\na headless Debian machine but don't run Debian on their own computer. If you\nrun into problems building the image on your OS, you can use the `docker-image`\ntarget.  This will build a minimal Debian container, install the dependencies\nand run the build process in the docker container, instead of your local OS.\nThat way, you can easily run this on non-Debian systems like Arch, Fedora etc.\nPlease note that the output files of the docker build are owned by root, so you\nneed to clean up with `sudo make clean` afterwards.\n\n## Remote Installation via ssh\n\nInsert the USB stick (or CD) in the target system and power it up. Wait a few\nminutes for the installer to boot and bring up the network. Find out the IP\naddress of the machine (e.g. from the router/DHCP server). Alternatively,\nconfigure static IP in the preseed file. Once the system is up you should be\nable to ping it. Now log in and complete the installation remotely:\n\n    ssh installer@yourmachine\n\nThe default password is `r00tme`; it can (and should!) be configured in the\npreseeding file.  Alternatively, you can configure passwordless login via ssh\nkey file – there is example code in the `preseed.cfg`. For this to work, you\nneed to provide the key file from a local web server.\n\nNOTE: The included minimal `preseed.cfg` assumes that you are connected via\nLAN cable (as a server should be). If you want to/must use a WIFI connection you\nneed to configure this.\n\n\n## Remote installation via serial console\n\nIf the serial interface was configured correctly, you should be able to connect\nthrough a terminal program (`cu`, `minicom`, etc.) via serial interface.  E.g.\n\n    cu -l /dev/ttyUSB0 -s 115200 \n\nor\n\n    screen /dev/ttyUSB0 115200\n\nWhere `/dev/ttyUSB0` is the serial interface on your local computer which is\nconnected to the server.\n\nIn the case of a virtual serial interface in iLO (or similar), please refer to\nthe manufacturers instructions on how to connect to it.\n\n\n## Random notes\n\nJust because it took me a while to realize: The Debian remote-installer uses\n`screen` to provide multiple virtual consoles. You can switch between them with\n`CTRL-a TAB`. See `man screen` for more information.\n\n\n# Contributing\n\nIf you found a bug or have an idea for improvements, feel free to open an issue and\ndescribe the fix or feature you have in mind. Please don't submit a pull request\nwithout discussing it, first.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilpagel%2Fdebian-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilpagel%2Fdebian-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilpagel%2Fdebian-headless/lists"}