infong
/
debi
mirror of https://github.com/bohanyang/debi
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
ai-readme-translation
Brent Yang 5 months ago committed by GitHub
parent e1db2c4d52
commit fe28cea5fe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 299 additions and 133 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 412
      README.md

412
README.md
Unescape View File

@ -1,154 +1,320 @@
# Debian Network Reinstall Script # Debian Network Reinstall Script
[中文说明 ↓](#中文说明) ## What is this?
## Introduction A script that reinstalls any VPS or physical machine to minimal Debian via network boot. Works by injecting the Debian installer into GRUB and automatically configuring the installation process.
This script is written to reinstall VPS/VMs to minimal Debian. **Perfect for:**
- Converting Oracle Cloud's Ubuntu images to Debian
- Removing cloud provider surveillance agents
- Creating minimal, clean Debian environments
- Automating installations with preseed/cloud-init
- Rescuing broken systems
## Platforms ## Quick Start
- ✔ KVM or physical machines ❌ Containers ```bash
- ✔ Debian or Ubuntu or Red Hat Linux as original OS with GRUB 2 bootloader # Download the script
- ✔ MBR or GPT partition table curl -fLO https://raw.githubusercontent.com/bohanyang/debi/master/debi.sh
- ✔ Multiple disks or LVM chmod +x debi.sh
- ✔ IPv4 or IPv6
- ✔ Legacy BIOS or UEFI boot
- ✔ Most VPS or cloud providers
- ⚠️ Google Compute Engine - **MUST** manually specify IP/CIDR and gateway of VPC
- ⚠️ AWS EC2 or Lightsail - Does **NOT** work with UEFI boot
## How It Works # Basic installation (creates user 'debian' with sudo access)
sudo ./debi.sh
1. Generate a preseed file to automate installation # Or install as root user instead
2. Download the 'Debian-Installer' to the `/boot` directory sudo ./debi.sh --user root
3. Append a menu entry of the installer to the GRUB2 configuration file
## Usage # Reboot when ready
sudo reboot
```
### 1. Download **Default settings:** Debian 12 (bookworm), DHCP networking, user `debian` with sudo access, you'll be prompted for password.
## Platform Support
| Platform | Status | Notes |
|----------|---------|-------|
| ✅ **KVM/Physical** | Full support | All features work |
| ✅ **Most VPS** | Full support | DigitalOcean, Vultr, Linode, etc. |
| ⚠️ **Google Cloud** | Requires manual network | Must use `--ip`, `--gateway` (DHCP broken) |
| ⚠️ **AWS EC2** | BIOS only | UEFI boot not yet supported |
| ❌ **Containers** | Not supported | Requires GRUB bootloader |
**Requirements:**
- KVM or physical machine (not containers)
- GRUB 2 bootloader
- Root access
## Regional Presets
| Preset | Mirror | DNS | NTP | Best for |
|--------|---------|-----|-----|----------|
| *Default* | deb.debian.org | Google DNS | time.google.com | Global |
| `--cloudflare` | deb.debian.org | Cloudflare | time.cloudflare.com | Global (privacy) |
| `--aws` | cdn-aws.deb.debian.org | Google DNS | time.aws.com | AWS instances |
| `--aliyun` | mirrors.aliyun.com | AliDNS | time.amazonaws.cn | China |
| `--ustc` | mirrors.ustc.edu.cn | DNSPod | time.amazonaws.cn | China |
| `--tuna` | mirrors.tuna.tsinghua.edu.cn | DNSPod | time.amazonaws.cn | China |
## Complete Options Reference
### System & User Configuration
| Option | Default | Description |
|--------|---------|-------------|
| `--version 12` | `12` | Debian version: `10`, `11`, `12`, `13` |
| `--suite bookworm` | `bookworm` | Debian suite: `stable`, `testing`, `sid`, etc. |
| `--user debian` | `debian` | Username (use `root` for root-only) |
| `--password PASSWORD` | *prompt* | User password (prompted if not specified) |
| `--authorized-keys-url URL` | *password auth* | SSH keys from URL (e.g., `https://github.com/user.keys`) |
| `--no-account-setup` | *create user* | Skip user creation (manual setup via console) |
| `--sudo-with-password` | *no password* | Require password for sudo commands |
| `--timezone UTC` | `UTC` | System timezone (e.g., `Asia/Shanghai`) |
| `--hostname NAME` | *current* | System hostname |
### Network Configuration
| Option | Default | Description |
|--------|---------|-------------|
| `--interface auto` | `auto` | Network interface (e.g., `eth0`, `eth1`) |
| `--ip ADDRESS` | *DHCP* | Static IP: `10.0.0.100`, `1.2.3.4/24`, `2001:db8::1/64` |
| `--static-ipv4` | *DHCP* | Use current IPv4 settings automatically |
| `--netmask MASK` | *auto* | Network mask: `255.255.255.0`, `ffff:ffff:ffff:ffff::` |
| `--gateway ADDRESS` | *auto* | Gateway IP (use `none` for no gateway) |
| `--dns '8.8.8.8 8.8.4.4'` | `1.1.1.1 1.0.0.1` | DNS servers for IPv4 |
| `--dns6 '2001:4860:4860::8888'` | `2606:4700:4700::1111` | DNS servers for IPv6 |
| `--ethx` | *consistent naming* | Use `eth0`/`eth1` instead of `enp0s3` style |
| `--ntp time.google.com` | `time.google.com` | NTP server |
### Network Console (Remote Installation)
| Option | Default | Description |
|--------|---------|-------------|
| `--network-console` | *disabled* | Enable SSH access during installation |
**Network Console Usage:**
1. Enable with `--network-console` and reboot
2. Wait 2-3 minutes for Debian installer to load components
3. SSH to your server: `ssh installer@YOUR_IP`
4. Use multiple terminals:
- **Alt+F1**: Main installer interface
- **Alt+F2**: Shell access
- **Alt+F3**: Additional shell
- **Alt+F4**: System logs (monitor automated installation progress)
- Navigate with Alt+Left/Alt+Right
> [!IMPORTANT]
> If `--authorized-keys-url` is used, SSH password authentication is disabled (SSH keys required), **but you still need to set a user password for VNC console and sudo access.**
### Storage & Partitioning
| Option | Default | Description |
|--------|---------|-------------|
| `--disk /dev/sda` | *auto-detect* | Target disk (**required** if multiple disks) |
| `--no-disk-partitioning` | *auto partition* | Manual partitioning via console |
| `--filesystem ext4` | `ext4` | Root filesystem type |
| `--force-gpt` | *enabled* | Create GPT partition table |
| `--no-force-gpt` | *use GPT* | Use MBR partition table instead |
| `--bios` | *auto-detect* | Force BIOS boot (creates BIOS boot partition) |
| `--efi` | *auto-detect* | Force EFI boot (creates EFI system partition) |
| `--esp 106` | `106` | EFI system partition size (106=100MB, 538=512MB, 1075=1GB) |
### Mirror & Repository Configuration
| Option | Default | Description |
|--------|---------|-------------|
| `--mirror-protocol https` | `https` | Mirror protocol: `http`, `https`, `ftp` |
| `--https` | *enabled* | Alias for `--mirror-protocol https` |
| `--mirror-host deb.debian.org` | `deb.debian.org` | Mirror hostname |
| `--mirror-directory /debian` | `/debian` | Mirror directory path |
| `--mirror-proxy URL` | *none* | HTTP proxy for downloads and APT |
| `--reuse-proxy` | *none* | Use existing `http_proxy` environment variable |
| `--security-repository URL` | *auto* | Security updates repo (use `mirror` for main mirror) |
### APT Repository Components
| Option | Default | Description |
|--------|---------|-------------|
| `--apt-non-free-firmware` | *enabled* | Include non-free firmware (Debian 12+) |
| `--apt-non-free` | *disabled* | Enable non-free repository |
| `--apt-contrib` | *disabled* | Enable contrib repository |
| `--apt-src` | *enabled* | Enable source repositories |
| `--apt-backports` | *enabled* | Enable backports repository |
| `--no-apt-non-free-firmware` | *use default* | Disable non-free firmware |
| `--no-apt-non-free` | *use default* | Disable non-free |
| `--no-apt-contrib` | *use default* | Disable contrib |
| `--no-apt-src` | *use default* | Disable source repositories |
| `--no-apt-backports` | *use default* | Disable backports |
### Package Installation
| Option | Default | Description |
|--------|---------|-------------|
| `--install 'pkg1 pkg2'` | *minimal* | Additional packages (space-separated, quoted) |
| `--install-recommends` | *enabled* | Install recommended packages |
| `--no-install-recommends` | *install recommends* | Skip recommended packages |
| `--upgrade safe-upgrade` | `safe-upgrade` | Package upgrade mode |
| `--safe-upgrade` | *default* | Safe package upgrades during install |
| `--full-upgrade` | *safe upgrade* | Full system upgrade (`dist-upgrade`) |
| `--no-upgrade` | *safe upgrade* | Skip package upgrades entirely |
### Kernel Options
| Option | Default | Description |
|--------|---------|-------------|
| `--kernel PACKAGE` | `linux-image-ARCH` | Kernel package name |
| `--cloud-kernel` | *standard* | Use cloud-optimized kernel |
| `--bpo-kernel` | *stable* | Use newer kernel from backports |
| `--firmware` | *auto-detect* | Include non-free firmware for hardware |
### Advanced Options
| Option | Default | Description |
|--------|---------|-------------|
| `--ssh-port 2222` | `22` | Custom SSH port |
| `--bbr` | *disabled* | Enable TCP BBR congestion control |
| `--architecture amd64` | *auto-detect* | Target architecture: `amd64`, `arm64`, `i386`, etc. |
| `--force-lowmem 1` | *auto* | Force low memory mode: `0`, `1`, `2` (for <512MB RAM) |
| `--no-force-efi-extra-removable` | *enabled* | Disable EFI extra removable media path |
| `--grub-timeout 5` | `5` | GRUB menu timeout in seconds |
### Debian Installer Options
| Option | Default | Description |
|--------|---------|-------------|
| `--release-d-i` | *auto* | Use release version of debian-installer |
| `--daily-d-i` | *auto* | Use daily build of debian-installer |
### Cloud-Init Integration
| Option | Default | Description |
|--------|---------|-------------|
| `--cidata /path/to/dir` | *none* | Custom cloud-init data directory |
**Cloud-Init Usage:**
```bash
# Create cloud-init configuration
mkdir my-cloud-config
echo "instance-id: my-server" > my-cloud-config/meta-data
cat > my-cloud-config/user-data << 'EOF'
#cloud-config
hostname: my-server
packages:
- htop
- git
EOF
# Use with installation
sudo ./debi.sh --cidata my-cloud-config
```
Download the script with curl: ### Development & Testing
| Option | Default | Description |
|--------|---------|-------------|
| `--dry-run` | *execute* | Generate configuration without installing |
| `--hold` | *reboot* | Don't reboot after installation |
| `--power-off` | *reboot* | Power off instead of reboot |
curl -fLO https://raw.githubusercontent.com/bohanyang/debi/master/debi.sh ## Examples
or wget: ### Oracle Cloud (Ubuntu → Debian)
```bash
sudo ./debi.sh --cloudflare --user debian
```
wget -O debi.sh https://raw.githubusercontent.com/bohanyang/debi/master/debi.sh ### Google Cloud Platform
```bash
# GCP requires manual network (replace with your VPC settings)
sudo ./debi.sh --ip 10.128.0.100/24 --gateway 10.128.0.1
```
### 2. Run ### Minimal Installation
```bash
sudo ./debi.sh --no-install-recommends --install 'curl git vim' --no-upgrade
```
Run the script under root or using sudo: ### China Deployment
```bash
sudo ./debi.sh --ustc --timezone Asia/Shanghai --dns '119.29.29.29'
```
chmod a+rx debi.sh ### Network Console Installation
sudo ./debi.sh ```bash
# Enable remote access during install (SSH keys for network, password still needed for VNC/sudo)
sudo ./debi.sh --network-console --authorized-keys-url https://github.com/yourusername.keys
# After reboot, SSH: ssh installer@YOUR_IP
```
By default, an admin user `debian` with sudo privilege will be created during the installation. Use `--user root` if you prefer. ### Static Network with Cloud-Init
```bash
### 3. Reboot sudo ./debi.sh --ip 192.168.1.100/24 --gateway 192.168.1.1 --cidata ./cloud-config/
```
If everything looks good, reboot the machine:
sudo shutdown -r now
Otherwise, you can run this command to revert all changes made by the script:
sudo rm -rf debi.sh /etc/default/grub.d/zz-debi.cfg /boot/debian-* && { sudo update-grub || sudo grub2-mkconfig -o /boot/grub2/grub.cfg; }
## Available Options
### Presets
| Region | Alias | Mirror | DNS | NTP |
|--------|----------------|--------------------------------------|------------|---------------------|
| Global | Default | https://deb.debian.org | Google | time.google.com |
| Global | `--cloudflare` | https://deb.debian.org | Cloudflare | time.cloudflare.com |
| Global | `--aws` | https://cdn-aws.deb.debian.org | Google | time.aws.com |
| China | `--ustc` | https://mirrors.ustc.edu.cn | DNSPod | time.amazonaws.cn |
| China | `--tuna` | https://mirrors.tuna.tsinghua.edu.cn | DNSPod | time.amazonaws.cn |
| China | `--aliyun` | https://mirrors.aliyun.com | AliDNS | time.amazonaws.cn |
* `--interface <string>` Manually select a network interface, e.g. eth1
* `--ethx` Disable *Consistent Network Device Naming* to get interface names like *ethX* back
* `--ip <string>` Disable the auto network config (DHCP) and configure a static IP address, e.g. `10.0.0.2`, `1.2.3.4/24`, `2001:2345:6789:abcd::ef/48`
* `--static-ipv4` Disable the auto network config (DHCP) and configure with the current IPv4 address and gateway detected automatically
* `--netmask <string>` e.g. `255.255.255.0`, `ffff:ffff:ffff:ffff::`
* `--gateway <string>` e.g. `10.0.0.1`, `none` if no gateway
* `--dns '8.8.8.8 8.8.4.4'`
* `--dns6 '2001:4860:4860::8888 2001:4860:4860::8844'` (effective only if IPv6 is specified)
* `--hostname <string>` FQDN hostname (includes the domain name), e.g. `server1.example.com`
* `--network-console` Enable the network console of the installer. `ssh installer@ip` to connect
* `--version 12` Supports: `10`, `11`, `12`, `13`
* `--suite bullseye` **Please use `--version` instead if you don't have special needs.** e.g. `stable`, `testing`, `sid`
* `--release-d-i` d-i (Debian Installer) for the released versions: 12 (bookworm), 11 (bullseye) and 10 (buster)
* `--daily-d-i` Use latest daily build of d-i (Debian Installer) for the unreleased version: 13 (trixie), sid (unstable)
* `--mirror-protocol http` or `https` or `ftp`
* `--https` alias to `--mirror-protocol https`
* `--reuse-proxy` Reuse the value of `http(s)_proxy` environment variable as the mirror proxy
* `--proxy, --mirror-proxy` Set an HTTP proxy for APT and downloads
* `--mirror-host deb.debian.org`
* `--mirror-directory /debian`
* `--security-repository http://security.debian.org/debian-security` Magic value: `'mirror' = <mirror-protocol>://<mirror-host>/<mirror-directory>/../debian-security`
* `--no-account-setup, --no-user` **(Manual installation)** Proceed account setup manually in VNC or remote console.
* `--username, --user debian` New user with `sudo` privilege or `root`
* `--password <string>` Password of the new user. **You'll be prompted if you choose to not specify it here**
* `--authorized-keys-url <string>` URL to your authorized keys for SSH authentication. e.g. `https://github.com/torvalds.keys`
* `--sudo-with-password` Require password when the user invokes `sudo` command
* `--timezone UTC` e.g. `Asia/Shanghai` for China (UTC+8) https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
* `--ntp time.google.com`
* `--no-disk-partitioning, --no-part` **(Manual installation)** Proceed disk partitioning manually in VNC or remote console
* `--disk <string>` Manually select a disk for installation. **Please remember to specify this when more than one disk is available!** e.g. `/dev/sda`
* `--no-force-gpt` By default, GPT rather than MBR partition table will be created. This option disables it.
* `--bios` Don't create *EFI system partition*. If GPT is being used, create a *BIOS boot partition* (`bios_grub` partition). Default if `/sys/firmware/efi` is absent. [See](https://askubuntu.com/a/501360)
* `--efi` Create an *EFI system partition*. Default if `/sys/firmware/efi` exists
* `--esp 106` Size of the *EFI system partition*. e.g. `106`, `538` and `1075` result to 100 MiB, 512 MiB, 1 GiB respectively
* `--filesystem ext4`
* `--kernel <string>` Choose an package for the kernel image
* `--cloud-kernel` Choose `linux-image-cloud-amd64` or `...arm64` as the kernel image
* `--bpo-kernel` Choose the kernel image from Debian Backports (newer version from the next Debian release)
* `--no-install-recommends`
* `--apt-non-free-firmware`, `--apt-non-free`, `--apt-contrib`, `--apt-src`, `--apt-backports`
* `--no-apt-non-free-firmware`, `--no-apt-non-free`, `--no-apt-contrib`, `--no-apt-src`, `--no-apt-backports`
* `--install 'ca-certificates libpam-systemd'` Install additional APT packages. Space-separated and quoted.
* `--safe-upgrade` **(Default)** `apt upgrade --with-new-pkgs`. [See](https://salsa.debian.org/installer-team/pkgsel/-/blob/master/debian/postinst)
* `--full-upgrade` `apt dist-upgrade`
* `--no-upgrade`
* `--bbr` Enable TCP BBR congestion control
* `--ssh-port <integer>` SSH port
* `--hold` Don't reboot or power off after installation
* `--power-off` Power off after installation rather than reboot
* `--architecture <string>` e.g. `amd64`, `i386`, `arm64`, `armhf`, etc.
* `--firmware` Load additional [non-free firmwares](https://wiki.debian.org/Firmware#Firmware_during_the_installation)
* `--no-force-efi-extra-removable` [See](https://wiki.debian.org/UEFI#Force_grub-efi_installation_to_the_removable_media_path)
* `--grub-timeout 5` How many seconds the GRUB menu shows before entering the installer
* `--force-lowmem <integer>` Valid values: 0, 1, 2. Force [low memory level](https://salsa.debian.org/installer-team/lowmem). Useful if your machine has memory less than 500M where level 2 is set (see issue #45). `--force-lowmem 1` may solve it.
* `--dry-run` Print generated preseed and GRUB entry without downloading the installer and actually saving them
* `--cidata ./cidata-example` Custom data for cloud-init. **VM provider's data source will be IGNORED.** See example.
## 中文说明
下载脚本：
### Advanced Custom Configuration
```bash
sudo ./debi.sh \
--version 12 \
--user admin \
--timezone Europe/London \
--disk /dev/nvme0n1 \
--filesystem btrfs \
--cloud-kernel \
--bbr \
--ssh-port 2222 \
--install 'htop iotop ncdu'
``` ```
curl -fLO https://raw.githubusercontent.com/bohanyang/debi/master/debi.sh && chmod a+rx debi.sh
## Troubleshooting
### Revert All Changes
```bash
# Remove all modifications and restore original GRUB
sudo rm -rf /etc/default/grub.d/zz-debi.cfg /boot/debian-*
sudo update-grub || sudo grub2-mkconfig -o /boot/grub2/grub.cfg
``` ```
运行脚本： ### Common Issues
**Multiple disks detected:**
```bash
# List available disks
lsblk
# Specify target disk
sudo ./debi.sh --disk /dev/sda
``` ```
sudo ./debi.sh --cdn --network-console --ethx --bbr --user root --password <新系统用户密码>
**Low memory VPS (<512MB):**
```bash
sudo ./debi.sh --force-lowmem 1
``` ```
* `--bbr` 开启 BBR **Network configuration fails:**
* `--ethx` 网卡名称使用传统形式，如 `eth0` 而不是 `ens3` ```bash
* `--cloud-kernel` 安装占用空间较小的 `cloud` 内核，但可能会导致 UEFI 启动的机器（如 Oracle、Azure 及 Hyper-V、Google Cloud 等）VNC 黑屏。BIOS 启动的普通 VPS 则没有此问题。 # Use current network settings
* 默认时区为 UTC，添加 `--timezone Asia/Shanghai` 可使用中国时区。 sudo ./debi.sh --static-ipv4
* 默认使用 Debian 官方 CDN 镜像源（deb.debian.org），添加 `--ustc` 可使用中科大镜像源。
如果没有报错可以重启： # Or configure manually
sudo ./debi.sh --ip YOUR_IP/CIDR --gateway YOUR_GATEWAY
```
**Need firmware for network card:**
```bash
sudo ./debi.sh --firmware
``` ```
sudo shutdown -r now
**Installation debugging:**
```bash
# Generate preseed file only
sudo ./debi.sh --dry-run
# Enable network console for remote access (SSH keys for remote, password for VNC/sudo)
sudo ./debi.sh --network-console --authorized-keys-url YOUR_KEYS_URL
``` ```
约 30 秒后可以尝试 SSH 登录 `installer` 用户，密码与之前设置的相同。如果成功连接，可以按 Ctrl-A 然后再按 4 监控安装日志。安装完成后会自动重启进入新系统。 ## How It Works
1. **Downloads Debian installer** to `/boot/debian-$VERSION/`
2. **Generates preseed file** with your configuration
3. **Modifies GRUB configuration** (adds installer menu entry)
4. **Injects configuration** into installer initramfs
5. **Updates GRUB** to include new boot option
**Changes made to your system:**
- Files added to `/boot/debian-*/`
- GRUB configuration in `/etc/default/grub.d/zz-debi.cfg`
- Updated GRUB menu
**These changes are safe and reversible** before reboot using the revert command above.
---
*Created by [@bohanyang](https://github.com/bohanyang) • [Issues](https://github.com/bohanyang/debi/issues) • [GitHub](https://github.com/bohanyang/debi)*

Write Preview
Loading…
Cancel
Save