-Installing Proxmox VE
----------------------
-include::attributes.txt[]
-
-{pve} ships as a set of Debian packages, so you can simply install it
-on top of a normal Debian installation, or download the installation
-CD-ROM and use that to install {pve} on your hardware.
-
-Installing on top of an existing Debian installation looks easy, but
-it presumes that you have correctly installed the base system, and you
-know how you want to configure and use the local storage. Network
-configuration is also completely up to you.
-
-In general, this is not trivial, especially when you use LVM or
-ZFS. This is why we provide an installation CD-ROM for {pve}. That
-installer just ask you a few questions, then partitions the local
-disk(s), installs all required packages and configures the system
-including a basic network setup. You can get a fully functional system
-within a few minutes, including the following:
+[[chapter_installation]]
+Installing {pve}
+================
+ifndef::manvolnum[]
+:pve-toplevel:
+endif::manvolnum[]
+ifdef::wiki[]
+:title: Installation
+endif::wiki[]
+
+{pve} is based on Debian. This is why the install disk images (ISO files)
+provided by Proxmox include a complete Debian system as well as all necessary
+{pve} packages.
+
+TIP: See the xref:faq-support-table[support table in the FAQ] for the
+relationship between {pve} releases and Debian releases.
+
+The installer will guide you through the setup, allowing you to partition the
+local disk(s), apply basic system configurations (for example, timezone,
+language, network) and install all required packages. This process should not
+take more than a few minutes. Installing with the provided ISO is the
+recommended method for new and existing users.
+
+Alternatively, {pve} can be installed on top of an existing Debian system. This
+option is only recommended for advanced users because detailed knowledge about
+{pve} is required.
+
+ifndef::wiki[]
+
+include::pve-system-requirements.adoc[]
+
+include::pve-installation-media.adoc[]
+
+endif::wiki[]
+
+
+[[installation_installer]]
+Using the {pve} Installer
+-------------------------
+
+The installer ISO image includes the following:
* Complete operating system (Debian Linux, 64-bit)
-* Partition the hard drive with ext4 (alternative ext3 or xfs) or ZFS
-* {pve} Kernel with LXC and KVM support
-* Complete toolset
-* Web based management interface
+* The {pve} installer, which partitions the local disk(s) with ext4, XFS,
+ BTRFS (technology preview), or ZFS and installs the operating system
+
+* {pve} Linux kernel with KVM and LXC support
+
+* Complete toolset for administering virtual machines, containers, the host
+ system, clusters and all necessary resources
+
+* Web-based management interface
+
+NOTE: All existing data on the selected drives will be removed during the
+installation process. The installer does not add boot menu entries for other
+operating systems.
+
+Please insert the xref:installation_prepare_media[prepared installation media]
+(for example, USB flash drive or CD-ROM) and boot from it.
+
+TIP: Make sure that booting from the installation medium (for example, USB) is
+enabled in your server's firmware settings. Secure boot needs to be disabled
+when booting an installer prior to {pve} version 8.1.
+
+[thumbnail="screenshot/pve-grub-menu.png"]
+
+After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
+will be displayed, and one of the following options can be selected:
+
+Install {pve} (Graphical)::
+
+Starts the normal installation.
+
+TIP: It's possible to use the installation wizard with a keyboard only. Buttons
+can be clicked by pressing the `ALT` key combined with the underlined character
+from the respective button. For example, `ALT + N` to press a `Next` button.
+
+Install {pve} (Terminal UI)::
+
+Starts the terminal-mode installation wizard. It provides the same overall
+installation experience as the graphical installer, but has generally better
+compatibility with very old and very new hardware.
+
+Install {pve} (Terminal UI, Serial Console)::
+
+Starts the terminal-mode installation wizard, additionally setting up the Linux
+kernel to use the (first) serial port of the machine for in- and output. This
+can be used if the machine is completely headless and only has a serial console
+available.
+
+[thumbnail="screenshot/pve-tui-installer.png"]
+
+Both modes use the same code base for the actual installation process to
+benefit from more than a decade of bug fixes and ensure feature parity.
+
+TIP: The 'Terminal UI' option can be used in case the graphical installer does
+not work correctly, due to e.g. driver issues. See also
+xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].
+
+Advanced Options: Install {pve} (Graphical, Debug Mode)::
+
+Starts the installation in debug mode. A console will be opened at several
+installation steps. This helps to debug the situation if something goes wrong.
+To exit a debug console, press `CTRL-D`. This option can be used to boot a live
+system with all basic tools available. You can use it, for example, to
+xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the
+xref:sysboot[bootloader] for an existing {pve} setup.
+
+Advanced Options: Install {pve} (Terminal UI, Debug Mode)::
+
+Same as the graphical debug mode, but preparing the system to run the
+terminal-based installer instead.
+
+Advanced Options: Install {pve} (Serial Console Debug Mode)::
+
+Same the terminal-based debug mode, but additionally sets up the Linux kernel to
+use the (first) serial port of the machine for in- and output.
+
+Advanced Options: Rescue Boot::
+
+With this option you can boot an existing installation. It searches all attached
+hard disks. If it finds an existing installation, it boots directly into that
+disk using the Linux kernel from the ISO. This can be useful if there are
+problems with the bootloader (GRUB/`systemd-boot`) or the BIOS/UEFI is unable to
+read the boot block from the disk.
+
+Advanced Options: Test Memory (memtest86+)::
+
+Runs `memtest86+`. This is useful to check if the memory is functional and free
+of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
+run this option.
+
+You normally select *Install {pve} (Graphical)* to start the installation.
+
+[thumbnail="screenshot/pve-select-target-disk.png"]
+
+The first step is to read our EULA (End User License Agreement). Following this,
+you can select the target hard disk(s) for the installation.
+
+CAUTION: By default, the whole server is used and all existing data is removed.
+Make sure there is no important data on the server before proceeding with the
+installation.
+
+The `Options` button lets you select the target file system, which
+defaults to `ext4`. The installer uses LVM if you select
+`ext4` or `xfs` as a file system, and offers additional options to
+restrict LVM space (see xref:advanced_lvm_options[below]).
+
+{pve} can also be installed on ZFS. As ZFS offers several software RAID levels,
+this is an option for systems that don't have a hardware RAID controller. The
+target disks must be selected in the `Options` dialog. More ZFS specific
+settings can be changed under xref:advanced_zfs_options[`Advanced Options`].
-Using the {pve} Installation CD-ROM
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+WARNING: ZFS on top of any hardware RAID is not supported and can result in data
+loss.
-This is the preferred and recommended installation method.
+[thumbnail="screenshot/pve-select-location.png"]
-NOTE: By default, the complete server is used and all existing data is
-removed.
+The next page asks for basic configuration options like your location, time
+zone, and keyboard layout. The location is used to select a nearby download
+server, in order to increase the speed of updates. The installer is usually able
+to auto-detect these settings, so you only need to change them in rare
+situations when auto-detection fails, or when you want to use a keyboard layout
+not commonly used in your country.
-Please insert the installation CD-ROM, then boot from that
-drive. Immediately afterwards you can choose the following menu
-options:
+[thumbnail="screenshot/pve-set-password.png", float="left"]
-Install Proxmox VE::
+Next the password of the superuser (`root`) and an email address needs to be
+specified. The password must consist of at least 5 characters. It's highly
+recommended to use a stronger password. Some guidelines are:
-Start normal installation.
+- Use a minimum password length of at least 12 characters.
-Install Proxmox VE (Debug mode)::
+- Include lowercase and uppercase alphabetic characters, numbers, and symbols.
-Start installation in debug mode. It opens a shell console at several
-installation steps, so that you can debug things if something goes
-wrong. Please press `CTRL-D` to exit those debug consoles and continue
-installation. This option is mostly for developers and not meant for
-general use.
+- Avoid character repetition, keyboard patterns, common dictionary words,
+ letter or number sequences, usernames, relative or pet names, romantic links
+ (current or past), and biographical information (for example ID numbers,
+ ancestors' names or dates).
-Rescue Boot::
+The email address is used to send notifications to the system administrator.
+For example:
-This option allows you to boot an existing installation. It searches
-all attached hard disks, and if it finds an existing installation,
-boots directly into that disk using the existing Linux kernel. This
-can be useful if there are problems with the boot block (grub), or the
-BIOS is unable to read the boot block from the disk.
+- Information about available package updates.
-Test Memory::
+- Error messages from periodic 'cron' jobs.
-Runs `memtest86+`. This is useful to check if your memory if
-functional and error free.
+[thumbnail="screenshot/pve-setup-network.png"]
-You normally select *Install Proxmox VE* to start the installation.
-After that you get prompted to select the target hard disk(s). The
-`Options` button lets you select the target file system, which
-defaults to `ext4`. The installer uses LVM if you select `ext3`,
-`ext4` or `xfs` as file system, and offers additional option to
-restrict LVM space (see <<advanced_lvm_options,below>>)
+All those notification mails will be sent to the specified email address.
-If you have more than one disk, you can also use ZFS as file system.
-ZFS supports several software RAID levels, so this is specially useful
-if you do not have a hardware RAID controller. The `Options` button
-lets you select the ZFS RAID level, and you can choose disks there.
+The last step is the network configuration. Network interfaces that are 'UP'
+show a filled circle in front of their name in the drop down menu. Please note
+that during installation you can either specify an IPv4 or IPv6 address, but not
+both. To configure a dual stack node, add additional IP addresses after the
+installation.
-The next pages just asks for basic configuration options like time
-zone and keyboard layout. You also need to specify your email address
-and select a superuser password.
+[thumbnail="screenshot/pve-installation.png", float="left"]
-The last step is the network configuration. Please note that you can
-use either IPv4 or IPv6 here, but not both. If you want to configure a
-dual stack node, you can easily do that after installation.
+The next step shows a summary of the previously selected options. Please
+re-check every setting and use the `Previous` button if a setting needs to be
+changed.
-If you press `Next` now, installation starts to format disks, and
-copies packages to the target. Please wait until that is finished,
-then reboot the server.
+After clicking `Install`, the installer will begin to format the disks and copy
+packages to the target disk(s). Please wait until this step has finished; then
+remove the installation medium and restart your system.
-Further configuration is done via the Proxmox web interface. Just
-point your browser to the IP address given during installation
-(https://youripaddress:8006). {pve} is tested for IE9, Firefox 10
-and higher, and Google Chrome.
+[thumbnail="screenshot/pve-install-summary.png"]
-NOTE: Default login is "root" (realm 'PAM') and the root password is
-defined during the installation process.
+Copying the packages usually takes several minutes, mostly depending on the
+speed of the installation medium and the target disk performance.
+When copying and setting up the packages has finished, you can reboot the
+server. This will be done automatically after a few seconds by default.
+
+.Installation Failure
+
+If the installation failed, check out specific errors on the second TTY
+('CTRL + ALT + F2') and ensure that the systems meets the
+xref:install_minimal_requirements[minimum requirements].
+
+If the installation is still not working, look at the
+xref:getting_help[how to get help chapter].
+
+
+Accessing the Management Interface Post-Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-login-window.png"]
+
+After a succesful installation and reboot of the system you can use the {pve}
+web interface for further configuration.
+
+. Point your browser to the IP address given during the installation and port
+ 8006, for example: https://youripaddress:8006
+
+. Log in using the `root` (realm 'PAM') username and the password chosen during
+ installation.
+
+. Upload your subscription key to gain access to the Enterprise repository.
+ Otherwise, you will need to set up one of the public, less tested package
+ repositories to get updates for security fixes, bug fixes, and new features.
+
+. Check the IP configuration and hostname.
+
+. Check the timezone.
+
+. Check your xref:chapter_pve_firewall[Firewall settings].
[[advanced_lvm_options]]
Advanced LVM Configuration Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The installer creates a Volume Group (VG) called `pve`, and additional
-Logical Volumes (LVs) called `root`, `data` and `swap`. The size of
-those volumes can be controlled with:
+The installer creates a Volume Group (VG) called `pve`, and additional Logical
+Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To
+control the size of these volumes use:
`hdsize`::
-Defines the total HD size to be used. This way you can save free
-space on the HD for further partitioning (i.e. for an additional PV
-and VG on the same hard disk that can be used for LVM storage).
+Defines the total hard disk size to be used. This way you can reserve free space
+on the hard disk for further partitioning (for example for an additional PV and
+VG on the same hard disk that can be used for LVM storage).
`swapsize`::
-To define the size of the `swap` volume. Default is the same size as
-installed RAM, with 4GB minimum and `hdsize/8` as maximum.
+Defines the size of the `swap` volume. The default is the size of the installed
+memory, minimum 4 GB and maximum 8 GB. The resulting value cannot be greater
+than `hdsize/8`.
++
+NOTE: If set to `0`, no `swap` volume will be created.
`maxroot`::
-The `root` volume size. The `root` volume stores the whole operation
-system.
+Defines the maximum size of the `root` volume, which stores the operation
+system. The maximum limit of the `root` volume size is `hdsize/4`.
`maxvz`::
-Define the size of the `data` volume, which is mounted at
-`/var/lib/vz`.
+Defines the maximum size of the `data` volume. The actual size of the `data`
+volume is:
++
+`datasize = hdsize - rootsize - swapsize - minfree`
++
+Where `datasize` cannot be bigger than `maxvz`.
++
+NOTE: In case of LVM thin, the `data` pool will only be created if `datasize` is
+bigger than 4GB.
++
+NOTE: If set to `0`, no `data` volume will be created and the storage
+configuration will be adapted accordingly.
`minfree`::
-To define the amount of free space left in LVM volume group `pve`.
-16GB is the default if storage available > 128GB, `hdsize/8` otherwise.
+Defines the amount of free space that should be left in the LVM volume group
+`pve`. With more than 128GB storage available, the default is 16GB, otherwise
+`hdsize/8` will be used.
+
-NOTE: LVM requires free space in the VG for snapshot creation (not
-required for lvmthin snapshots).
+NOTE: LVM requires free space in the VG for snapshot creation (not required for
+lvmthin snapshots).
+
+[[advanced_zfs_options]]
+Advanced ZFS Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The installer creates the ZFS pool `rpool`, if ZFS is used. No swap space is
+created but you can reserve some unpartitioned space on the install disks for
+swap. You can also create a swap zvol after the installation, although this can
+lead to problems (see xref:zfs_swap[ZFS swap notes]).
+
+`ashift`::
+
+Defines the `ashift` value for the created pool. The `ashift` needs to be set at
+least to the sector-size of the underlying disks (2 to the power of `ashift` is
+the sector-size), or any disk which might be put in the pool (for example the
+replacement of a defective disk).
+
+`compress`::
+
+Defines whether compression is enabled for `rpool`.
+
+`checksum`::
+
+Defines which checksumming algorithm should be used for `rpool`.
+
+`copies`::
+
+Defines the `copies` parameter for `rpool`. Check the `zfs(8)` manpage for the
+semantics, and why this does not replace redundancy on disk-level.
+
+`ARC max size`::
+
+Defines the maximum size the ARC can grow to and thus limits the amount of
+memory ZFS will use. See also the section on
+xref:sysadmin_zfs_limit_memory_usage[how to limit ZFS memory usage] for more
+details.
+
+`hdsize`::
+
+Defines the total hard disk size to be used. This is useful to save free space
+on the hard disk(s) for further partitioning (for example to create a
+swap-partition). `hdsize` is only honored for bootable disks, that is only the
+first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123].
ZFS Performance Tips
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
+
+ZFS works best with a lot of memory. If you intend to use ZFS make sure to have
+enough RAM available for it. A good calculation is 4GB plus 1GB RAM for each TB
+RAW disk space.
-ZFS uses a lot of memory, so it is best to add additional 8-16GB RAM
-if you want to use ZFS.
+ZFS can use a dedicated drive as write cache, called the ZFS Intent Log (ZIL).
+Use a fast drive (SSD) for it. It can be added after installation with the
+following command:
-ZFS also provides the feature to use a fast SSD drive as write cache. The
-write cache is called the ZFS Intent Log (ZIL). You can add that after
-installation using the following command:
+----
+# zpool add <pool-name> log </dev/path_to_fast_ssd>
+----
- zpool add <pool-name> log </dev/path_to_fast_ssd>
+[[nomodeset_kernel_param]]
+Adding the `nomodeset` Kernel Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Problems may arise on very old or very new hardware due to graphics drivers. If
+the installation hangs during boot, you can try adding the `nomodeset`
+parameter. This prevents the Linux kernel from loading any graphics drivers and
+forces it to continue using the BIOS/UEFI-provided framebuffer.
-ifdef::wiki[]
+On the {pve} bootloader menu, navigate to 'Install {pve} (Terminal UI)' and
+press `e` to edit the entry. Using the arrow keys, navigate to the line starting
+with `linux`, move the cursor to the end of that line and add the
+parameter `nomodeset`, separated by a space from the pre-existing last
+parameter.
-link:/wiki/Install_Proxmox_VE_on_Debian_Jessie[Install Proxmox VE on Debian Jessie]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Then press `Ctrl-X` or `F10` to boot the configuration.
-endif::wiki[]
+[[installation_unattended]]
+Unattended Installation
+-----------------------
+
+It is possible to install {pve} automatically in an unattended manner. This
+enables you to fully automate the setup process on bare-metal. Once the
+installation is complete and the host has booted up, automation tools like
+Ansible can be used to further configure the installation.
+
+The necessary options for the installer must be provided in an answer file. This
+file allows the use of filter rules to determine which disks and network cards
+should be used.
+
+To use the automated installation, it is first necessary to prepare an
+installation ISO.
+https://pve.proxmox.com/wiki/Automated_Installation[Visit our wiki] for more
+details and information on the unattended installation.
ifndef::wiki[]
Install {pve} on Debian
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
-{pve} ships as a set of Debian packages, so you can simply install it
-on top of a normal Debian installation. After configuring the
-repositories, you need to run:
+{pve} ships as a set of Debian packages and can be installed on top of a standard
+Debian installation.
+xref:sysadmin_package_repositories[After configuring the repositories] you need
+to run the following commands:
-[source,bash]
----
-apt-get update
-apt-get install proxmox-ve
+# apt-get update
+# apt-get install proxmox-ve
----
-You can find a detailed step by step howto on the {pve}
-http://pve.proxmox.com/wiki/Install_Proxmox_VE_on_Debian_Jessie[wiki].
+Installing on top of an existing Debian installation looks easy, but it presumes
+that the base system has been installed correctly and that you know how you want
+to configure and use the local storage. You also need to configure the network
+manually.
+
+In general, this is not trivial, especially when LVM or ZFS is used.
+
+A detailed step by step how-to can be found on the
+{webwiki-url}Install_Proxmox_VE_on_Debian_12_Bookworm[wiki].
-endif::wiki[]
+endif::wiki[]
ifdef::wiki[]
Video Tutorials
-~~~~~~~~~~~~~~~
-
-* List of all official tutorials on our
- http://www.youtube.com/proxmoxve[Proxmox VE YouTube Channel]
+---------------
-* Tutorials in Spanish language on
- http://www.youtube.com/playlist?list=PLUULBIhA5QDBdNf1pcTZ5UXhek63Fij8z[ITexperts.es
- YouTube Play List]
+See the list of all official tutorials on our
+https://www.youtube.com/proxmoxve[{pve} YouTube Channel]
See Also
-~~~~~~~~
+--------
+
+* link:/wiki/Prepare_Installation_Media[Prepare Installation Media]
+
+* link:/wiki/Install_Proxmox_VE_on_Debian_12_Bookworm[Install Proxmox VE on Debian 12 Bookworm]
+
+* link:/wiki/System_Requirements[System Requirements]
* link:/wiki/Package_Repositories[Package Repositories]
* link:/wiki/Installation:_Tips_and_Tricks[Installation: Tips and Tricks]
endif::wiki[]
-
projects / pve-docs.git / blobdiff