Name
----
-grml-debootstrap - wrapper around debootstrap for installing plain Debian via grml
+grml-debootstrap - wrapper around debootstrap for installing plain Debian
Synopsis
--------
Introduction
------------
-grml-debootstrap is a wrapper suite around debootstrap
-(and cdebootstrap if you want) for installing a plain Debian
-system via grml very fast and easy.
+grml-debootstrap is a wrapper suite around debootstrap (and cdebootstrap and mmdebstrap if you
+want) for installing a plain Debian system very fast and easy.
-All you have to do is adjust a few variables in configuration file
-/etc/debootstrap/config (or specify some variables via commandline) and invoke
-grml-debootstrap without any further options then.
+All you have to do is adjust a few variables in the configuration file
+/etc/debootstrap/config or specify some command line options and invoke
+grml-debootstrap. If invoked without any configuration modifications or command
+line options a dialog based front end will be available to control some basic
+configuration options.
-A plain and base Debian system will be installed on the given
-device (or directory) then. Customization of this process is
-possible as well.
+A plain and base Debian system will be installed on the given device, directory
+or virtual image file then. Customization of this process is possible as well.
-CAUTION: The grml team does not take responsibility for loss of any data!
+CAUTION: The Grml team does not take responsibility for loss of any data!
Options and environment variables
---------------------------------
-*-h*, *--help*::
- Show summary of options and exit.
+*--arch* _architecture_::
-*-v*, *--version*::
- Show version of program and exit.
+ Set target architecture you want to install. Defaults to the architecture
+ you are currently running. If you're running an amd64 kernel and want to
+ deploy an i386 system use this option. Note: deploying amd64 from an i386
+ kernel does *not* work. Example: "_--arch i386_"
-*--grub* <_device_>::
- Where do you want to install grub to? Use grub syntax for specifying.
- Do not forget to set groot as well. Leave empty to avoid installation of grub.
+*--backportrepos*::
-*--groot* <_device_>::
- Specify root device for usage in grub (corresponds with $TARGET).
- Again, use grub syntax for specifying.
- Corresponding with configuration variable GROOT.
+ Enable Debian's Backports repository via the
+ /etc/apt/sources.list.d/backports.list configuration file. This provides the
+ option to install Debian packages from Debian's backports repository.
-*--boot_append* <_appendline for the kernel_>::
- Specify appendline for the kernel.
+*--bootappend* _appendline-for-the-kernel_::
+
+ Specify appendline for the kernel.
E.g. "_pci=nomsi_"
-*-m*, *--mirror* <_URL_>::
- Specify mirror which should be used for apt-get/aptitude. Notice that
- specifying the mirror also sets the chrootmirror to the given value.
- Corresponding with configuration variables MIRROR and CHROOTMIRROR.
+*-c*, *--config* _file_::
+
+ Use specified configuration file, defaults to /etc/debootstrap/config.
+
+*--chroot-scripts* _directory_::
+
+ Execute chroot scripts from specified directory. This allows customisation
+ of the chroot setup, the executable script(s) present in the given directory
+ are executed at the end of the chroot procedure.
+ Default directory: /etc/debootstrap/chroot-scripts/
+
+*--contrib*::
+
+ Enable the 'contrib' repository in COMPONENTS. By default only
+ the 'main' repository is enabled.
+
+*-d*, *--confdir* _path_::
+
+ Place of configuration files for debootstrap, defaults to /etc/debootstrap.
+
+*--debconf* _file_::
+
+ Use specified file for preseeding Debian packages instead of using
+ the default <confdir>/debconf-selections.
+
+*--debopt* _params_::
+
+ Extra parameters passed to the debootstrap command.
+
+*--debug*::
+
+ Execute in very verbose way. Useful for debugging possible problems
+ with grml-debootstrap or identify what's actually executed.
+
+*--defaultinterfaces*::
+
+ Install a default /etc/network/interfaces file (enabling DHCP for all local
+ Ethernet, WLAN and WWAN interfaces using predictable network interface names
+ and using eth0 as traditional interface name for backward compatibility)
+ instead of taking over config from host system.
+ This option is automatically enabled when using --vm or --vmfile.
+
+*--efi* _device_::
+
+ Partition where EFI boot manager should be installed to. If the
+ specified device doesn't use a FAT filesystem yet grml-debootstrap
+ automatically creates the filesystem. If a FAT filesystem is already
+ present the filesystem creation is skipped. Please ensure that it's
+ a valid FAT32 filesystem and the partition has the 'boot' and 'esp'
+ flags enabled. This option requires EFI support on the running system
+ and the option is NOT supported for Virtual Machine deployments.
+
+*--filesystem* _filesystem_::
+
+ Filesystem that should be created when installing to a partition.
+ If unset defaults to ext4. Valid values are all filesystems that
+ can be created through mkfs._filesystem_.
+
+*--force*::
+
+ Skip user acknowledgement and do not prompt for user input.
+
+*--grmlrepos*::
+
+ Enable Grml.org's Debian repository (http://deb.grml.org/) via the
+ /etc/apt/sources.list.d/grml.list configuration file. This provides the
+ option to install Debian packages from Grml's repository.
-*-i*, *--iso* <_/mntpoint_>::
- Specify mountpoint where you have a Debian ISO mounted loopback.
+*--grub* _device_::
+
+ Device where grub should be installed to. Note that only the MBR (master
+ boot record) can be used (/dev/sda, /dev/sdb,...). Partitions (like
+ /dev/sda1, /dev/sdb2,...) are NOT supported because grub2 doesn't support
+ installation into the PBR (partition boot record) anymore. Usage example:
+ '--grub /dev/sda'. Note: just do not set this option to avoid installation
+ of grub.
+
+*--help*, *-h*::
+
+ Show summary of options and exit.
+
+*--hostname* _hostname_::
+
+ Use specified hostname instead of the default (being $HOSTNAME or if unset 'grml').
+
+*-i*, *--iso* _/mntpoint_::
+
+ Specify mount point where you have a Debian ISO mounted loopback.
Using this option instead of the mirror option gives you the possibility
to install the base-system without network access. Make sure you
- mounted the according Debian-ISO to the given <_/mntpoint_>. See section
+ mounted the according Debian-ISO to the given _/mntpoint_. See section
'Usage examples' for a demonstration.
-*-p*, *--mntpoint* <_/mntpoint_>::
- Specify mountpoint that should be used for mounting the target system.
+*--keep_src_list*::
+
+ Do not overwrite user provided /etc/apt/sources.list.
+
+*-m*, *--mirror* _URL_::
+
+ Specify mirror which should be used for apt-get/aptitude.
+ Corresponding with configuration variable MIRROR.
+
+*--nodebootstrap*::
+
+ Skip debootstrap, only do configuration to the target.
+
+*--nointerfaces*::
+
+ Do not copy /etc/network/interfaces from host system to the target.
+
+*--nokernel*::
+
+ Skip installation of default kernel images. This option might be
+ interesting for you if you want a Debian system which doesn't
+ need to provide regular boot, e.g. a system which provides
+ ISOs for booting via GRUB using grml-rescueboot.
+
+*--non-free*::
+
+ Enable the 'non-free' repository in COMPONENTS.
+ For bookworm and newer Debian releases also the 'non-free-firmware' repository gets enabled.
+ By default only the 'main' repository is enabled.
+
+*--nopackages*::
+
+ Skip installation of packages defined in /etc/debootstrap/packages.
+
+*--nopassword*::
+
+ Do not prompt for the root password. Note: Use the '--password' option if
+ you want to set the root password during an automatic installation but don't
+ want to use the interactive dialog.
+
+*-p*, *--mntpoint* _/mntpoint_::
+
+ Specify mount point that should be used for mounting the target system.
Corresponding with configuration variable MNTPOINT.
+ Note: this option has no effect if option -t is given and represents a
+ directory.
+
+*--packages* _file_::
+
+ Use specified file as list for packages that should be installed instead of
+ the default package list file <confdir>/packages.
+
+*--password* _password_::
-*--password* <_password_>::
Use specified password as password for user root. Use with caution, as your
- commandline might be visible in the process list and the shell history.
+ command line might be visible in the process list and the shell history.
It's meant for automatic installation only.
-*-r*, *--release* <_releasename_>::
- Specify release of new Debian system. Supported releases: sarge, etch, lenny and sid.
- Corresponding with configuration variable RELEASE.
+*--post-scripts* _directory_::
+
+ Execute scripts from specified directory after executing the chroot script.
+ This allows customisation of the system after the chroot has been set up.
+ The environment variable $MNTPOINT is available inside the scripts for
+ direct access of the chroot.
+ Default directory: /etc/debootstrap/post-scripts/
+
+*--pre-scripts* _directory_::
+
+ Execute scripts from specified directory before executing the chroot
+ script. This allows customisation of the system before the chroot has
+ been set up. The environment variable $MNTPOINT is available inside the
+ scripts for direct access of the chroot.
+ Default directory: /etc/debootstrap/pre-scripts/
+
+*-r*, *--release* _releasename_::
+
+ Specify release of new Debian system. Supported releases names:
+ jessie, stretch, buster, bullseye, bookworm and sid.
+ Corresponding with configuration variable RELEASE. Default release: bookworm
+
+*--remove-configs*::
+
+ Delete grml-debootstrap configuration files (/etc/debootstrap/*) from installed
+ system. Useful for reproducible builds or if you don't want to leak information.
+
+*--sshcopyauth*::
+
+ Use locally available _$HOME/.ssh/authorized_keys_ to authorise root login on the target system.
+ This installs _$HOME/.ssh/authorized_keys_ as _/root/.ssh/authorized_keys_ on
+ the target system. If a different file than _$HOME/.ssh/authorized_keys_ should
+ be used, the environment variable _AUTHORIZED_KEYS_SOURCE_ can be used.
+
+*--sshcopyid*::
+
+ Use locally available public keys to authorise root login on the target system.
+ Similar to ssh-copy-id(1) (without the -i option) it checks if `ssh-add -L`
+ provides any output, and if so those keys are appended to
+ _/root/.ssh/authorized_keys_ (creating the file and directory (with mode 0700)).
+
+*-t*, *--target* _target_::
-*-t*, *--target* <_target_>::
Target partition (/dev/...) or directory (anything else without /dev at the
beginning).
-WARNING: the commandline parsing of grml-debootstrap does not validate the provided
-arguments for the commandline options. Please be careful and check docs and
-/etc/debootstrap/config for further information.
+*-v*, *--verbose*::
+
+ Increase verbosity.
+
+*--vm*::
+
+ Set up a Virtual Machine on an existing block device, which will be
+ partitioned.
+ This allows deployment of a Virtual Machine. The options needs to be
+ combined with the --target option.
+ This option automatically enables the --defaultinterfaces option.
+ Usage example: --vm --target /dev/mapper/your-vm-disk
+
+*--vmfile*::
+
+ Set up a Virtual Machine using a regular file instead of installing to a
+ partition/block device or directory. This allows deployment of a Virtual
+ Machine. The options needs to be combined with the --target option
+ ('qemu-img create -f raw ...' is executed on the specified target).
+ This option automatically enables the --defaultinterfaces option.
+ Usage example: --vmfile --target /mnt/sda1/qemu.img
+
+*--vmsize* _size_::
+
+ Use specified size for size of Virtual Machine disk file. If not specified it
+ defaults to 2G (being 2GB). Syntax as supported by qemu-img (see manpage
+ qemu-img(1) for details.
+ Usage example: --vmsize 3G
+
+*--vmefi*::
+
+ Create an EFI boot partition for the VM.
+
+*-V*, *--version*::
+
+ Show version of program and exit.
+
+WARNING: the command line parsing of grml-debootstrap usually does not validate
+the provided arguments for the command line options. Please be careful and check
+docs and /etc/debootstrap/config for further information.
+
+Networking
+----------
+
+By default (that is, if none of the options *--nointerfaces*,
+*--defaultinterfaces*, *--vmfile* or *--vm* are given) /etc/network/interfaces
+will be copied from the host to the target system.
Usage examples
---------------
- grml-debootstrap --target /dev/hda1 --grub hd0 --groot hd0,0
+ grml-debootstrap --target /dev/sda1 --grub /dev/sda
+
+Install default Debian release (bookworm) on /dev/sda1 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+
+ grml-debootstrap --release stretch --target /dev/sda1 --grub /dev/sda --hostname debian01 --password changeme
+
+Install Debian release stretch on /dev/sda1 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+Set hostname to 'debian01' and password for user root to 'changeme'.
-Install default Debian release (stable/etch) on /dev/hda1 and install bootmanager
-Grub in MBR (master boot record) of /dev/hda and use /dev/hda1 as system partition.
+ grml-debootstrap --target /dev/sda6 --grub /dev/sda --release sid
- grml-debootstrap --target /dev/hda6 --grub hd0 --groot hd0,5 --release sid
+Install Debian unstable/sid on /dev/sda6 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
-Install Debian unstable/sid on /dev/hda6, install bootmanager
-Grub in MBR (master boot record) of /dev/hda and use /dev/hda6 as system partition.
+ DEBOOTSTRAP=mmdebstrap grml-debootstrap --target /dev/sda1 --grub /dev/sda
+Install default Debian release (bookworm) on /dev/sda1 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+Use mmdebstrap instead of default debootstrap tool for bootstrapping.
+
+ grml-debootstrap --target /dev/mapper/vg0-rootfs --grub /dev/sda
+
+Install default Debian release (bookworm) on LVM device /dev/mapper/vg0-rootfs and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+
+ grml-debootstrap --efi /dev/sda1 --target /dev/sda2 --grub /dev/sda
+
+Install default Debian release (bookworm) on /dev/sda2 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+Use /dev/sda1 as EFI partition (requires EFI support in booted system).
+
+ mount /dev/sda1 /data/chroot
grml-debootstrap --target /data/chroot
-Install default Debian release (stable/etch) in directory /data/chroot (without
-any bootloader).
+Install default Debian release (bookworm) in directory /data/chroot (without any bootloader).
+
+ grml-debootstrap --target /dev/sda3 --grub /dev/sda --mirror ftp://ftp.tugraz.at/mirror/debian
- grml-debootstrap --target /dev/sda3 --grub hd0 --groot hd0,2 --mirror ftp://ftp.tugraz.at/mirror/debian
+Install default Debian release (bookworm) on /dev/sda3 and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+Use specified mirror instead of the default (http://deb.debian.org/debian) one.
-Install default Debian release (stable/etch) on /dev/sda3 and install bootmanager
-Grub in MBR (master boot record) of /dev/sda and use /dev/sda3 as system partition.
-Use specified mirror instead of the default (ftp://ftp.debian.de/debian) one.
+ mount /dev/sda1 /mnt/sda1
+ grml-debootstrap --vmfile --vmsize 3G --target /mnt/sda1/qemu.img
- mount -o loop /mnt/hda6/debian-40r0-i386-CD-1.iso /mnt/iso
- grml-debootstrap --target /dev/hda1 --grub hd0 --groot hd0,0 --iso file:/mnt/iso/debian/
+Install default debian release (bookworm) in a Virtual Machine file with 3GB disk size (including GRUB as bootmanager in MBR of the virtual disk file):
-Install Debian stable/etch on /dev/hda1 using the loopback mounted Debian-ISO
-for the base-system and install bootmanager Grub in MBR (master boot record) of
-/dev/hda and use /dev/hda1 as system partition. Please notice, that the chroot
-system requires network access for all packages which are not part of the
-ISO.
+ mount -o loop ./debian-CD-1.iso /media/cdrom
+ grml-debootstrap --target /dev/sda1 --grub /dev/sda --iso /media/cdrom
+
+Install Debian on /dev/sda1 using the loopback mounted Debian-ISO for the base-system and install bootmanager GRUB in MBR (master boot record) of /dev/sda.
+Please notice, that the chroot system requires network access for all packages which are not part of the ISO.
Files
-----
/etc/debootstrap/config
-Main configuration file. You have to adjust it according to your needs
-before you are able to run grml-debootstrap.
+Main configuration file. Adjust it according to your needs if you want to
+execute grml-debootstrap in the non-interactive mode without any special command
+line arguments.
/etc/debootstrap/chroot-script
Defines the software packages which should be installed in the new
Debian system by default.
- /etc/debootstrap/extrapackages
-
-Debian Packages dropped here will be installed into the new Debian system by
-default (Controlvariable: EXTRAPACKAGES)
-
- /etc/debootstrap/stages/
+ /etc/debootstrap/extrapackages/
-The default directory for storing information about executed stages. Every
-single function of grml-debootstrap will write 'done' to the stages directory
-into a file named as the function itself if it has been executed successfully.
-You can adjust the location of the directory via configuration variable STAGES
-via /etc/debootstrap/config. Please notice that you have to remove the stages
-directory on your own if you want to re-execute grml-debootstrap after running it
-successfully once. This should avoid recurrent execution by error of
-grml-debootstrap (which might delete present data).
+Debian Packages dropped in this directory will be installed into the new Debian
+system by default (Control variable: EXTRAPACKAGES)
Customization
-------------
You can control execution of grml-debootstrap via adjusting
/etc/debootstrap/config for some main stuff or via setting some selected
-variables via commandline. The packages which should be installed in the new
+variables via command line. The packages which should be installed in the new
Debian system can be defined via the file /etc/debootstrap/packages. If you
want to put existing files to the new Debian system you can place them into the
(by default non-existing) directories boot, etc, share, usr and var in
/etc/debootstrap/. Every existing directory will be copied to the new Debian
system then. If you want to install additional packages that are not available
-via the grml or debian mirror drop them into /etc/debootstrap/extrapackages and
-take sure that EXTRAPACKAGES is set to "yes".
+via the Grml or Debian mirror drop them into /etc/debootstrap/extrapackages and
+make sure that EXTRAPACKAGES is set to "yes".
Automatic installation
----------------------
If environment variable AUTOINSTALL is set grml-debootstrap can be executed in a
full automatic mode. While this mode isn't really useful for interactive
execution (just configure /etc/debootstrap/configure or specify the relevant
-variables on the commandline instead) it is meant for use via bootoption
-debian2hd. The bootoption debian2hd (more precise: the kernelname on bootprompt)
-supports the following bootoptions (they correspond with the commandline options
-mentioned above):
+variables on the command line instead) it is meant for use via boot option
+debian2hd on the Grml live system. The boot option debian2hd (more precise: the
+kernelname at the bootprompt) supports the following boot options (they
+correspond with the command line options mentioned above):
target=...
The target partition/directory of the new Debian system. Usage example:
-target=/dev/hda1
+target=/dev/sda1
grub=...
-Where do you want to install grub to? Use grub syntax for specifying.
-Usage example: grub=hd0
-
- groot=...
-
-Specify root device for usage in grub (corresponds with $TARGET).
-Again, use grub syntax for specifying. Usage example: groot=hd0,0
+Where do you want to install grub to? Usage example: grub=/dev/sda
release=...
-Specify release of new Debian system. Defaults to Debian stable.
-Supported relases: sarge, etch, lenny and sid. Usage example: release=sid
+Specify release of new Debian system. Defaults to Debian bookworm.
+Supported releases: jessie, stretch, buster, bullseye, bookworm and sid.
+Usage example: release=bullseye
mirror=...
Specify mirror which should be used for apt-get/aptitude instead
-of the default one (ftp://ftp.debian.de/debian).
+of the default one (http://deb.debian.org/debian).
Usage example: mirror=ftp://ftp.tugraz.at/mirror/debian
password=...
Set password of user root without prompting for it but set it to the given
argument. Usage example: password=AiTh5ahn
-Usage example for automatic installation:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Usage example for automatic installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- debian2hd target=/dev/hda1 grub=hd0 groot=hd0,0 mirror=ftp://ftp.tugraz.at/mirror/debian password=foobar
+ debian2hd target=/dev/sda1 grub=/dev/sda mirror=ftp://ftp.tugraz.at/mirror/debian password=foobar
-You have to enter this commandline at the bootprompt of grml. Please make sure
-that /dev/hda1 is the partition where you really want to install your new Debian
-system.
+You have to enter this command line at the bootprompt of the Grml live system.
+Please make sure that /dev/sda1 is the partition where you really want to
+install your new Debian system.
[NOTE]
Automatic installation within booting process is done in grml-autoconfig via
setting environment variable AUTOINSTALL and creation of
/usr/bin/grml-debootstrap_noninteractive with the available and relevant
-bootoptions for grml-debootstrap.
+boot options for grml-debootstrap.
Supported Releases
------------------
include::releasetable.txt[]
[NOTE]
-.Sarge-Release
-=====================================================================
-[1] Please notice that Sarge is the current old-stable within Debian.
-grml-debootstrap can handle the release but you really should not
-use Sarge anymore unless you really know what you are doing. Choose
-Etch instead.
-=====================================================================
+.jessie/stretch/buster release
+================================================================================
+[1] Please notice that releases like jessie, stretch and buster are unsupported releases within Debian nowadays.
+grml-debootstrap can handle the releases but you really should not use them anymore unless you really know what you are doing.
+Even older versions are also entirely unsupported by grml-debootstrap.
+
+Choose the current Debian stable version instead.
+See https://wiki.debian.org/DebianReleases for the list of supported releases.
+
+Notice that you need to specify a specific mirror providing old releases, the default (http://deb.debian.org/debian) doesn't provide them any longer.
+Set the mirror to e.g. http://archive.debian.org/debian/ if you don't have your own Debian mirror.
+
+Older releases might also fail to install when running on top of recent kernel versions,
+throwing segfaults during debootstrap. This can be identified by the following messages inside kernel log (check with 'dmesg'):
+
+ dpkg[...] vsyscall attempted with vsyscall=none ip:[...]
+ dpkg[...]: segfault at [...]
+
+To work around this issue boot your system with the kernel boot option 'vsyscall=emulate'.
+================================================================================
+
+[NOTE]
+.unstable and testing releases
+================================================================================
+[2] Please notice that Debian/testing and Debian/unstable (sid) might
+not be always installable due to their nature. What _might_ work instead is
+deploying a stable release and upgrade it after installation finished.
+================================================================================
Bugs
----
-Probably. Please send bugreports to Michael Prokop <mika@grml.org>.
+Please report bugs towards https://github.com/grml/grml-debootstrap/issues
See also
--------
-debootstrap (8), cdebootstrap (1).
+debootstrap (8), cdebootstrap (1), mmdebstrap(1).
Author
------