]>
Commit | Line | Data |
---|---|---|
9a6dc394 | 1 | [[chapter_installation]] |
32caab0e AL |
2 | Installing {pve} |
3 | ================ | |
194d2f29 | 4 | ifndef::manvolnum[] |
5f09af76 | 5 | :pve-toplevel: |
194d2f29 DM |
6 | endif::manvolnum[] |
7 | ifdef::wiki[] | |
cb84ed18 | 8 | :title: Installation |
5f09af76 DM |
9 | endif::wiki[] |
10 | ||
32caab0e | 11 | {pve} is based on Debian. This is why the install disk images (ISO files) |
bdf0aff2 TL |
12 | provided by Proxmox include a complete Debian system as well as all necessary |
13 | {pve} packages. | |
14 | ||
15 | TIP: See the xref:faq-support-table[support table in the FAQ] for the | |
7f7446cf | 16 | relationship between {pve} releases and Debian releases. |
2d99ce9b | 17 | |
19d1b3de SI |
18 | The installer will guide you through the setup, allowing you to partition the |
19 | local disk(s), apply basic system configurations (for example, timezone, | |
20 | language, network) and install all required packages. This process should not | |
21 | take more than a few minutes. Installing with the provided ISO is the | |
22 | recommended method for new and existing users. | |
d91f8c1e | 23 | |
32caab0e AL |
24 | Alternatively, {pve} can be installed on top of an existing Debian system. This |
25 | option is only recommended for advanced users because detailed knowledge about | |
26 | {pve} is required. | |
d91f8c1e | 27 | |
bc1c71d4 DM |
28 | ifndef::wiki[] |
29 | ||
30 | include::pve-system-requirements.adoc[] | |
31 | ||
44ea3fd6 TL |
32 | include::pve-installation-media.adoc[] |
33 | ||
bc1c71d4 DM |
34 | endif::wiki[] |
35 | ||
5eba0743 | 36 | |
9a6dc394 | 37 | [[installation_installer]] |
2c6fed66 TM |
38 | Using the {pve} Installer |
39 | ------------------------- | |
d91f8c1e | 40 | |
44ea3fd6 | 41 | The installer ISO image includes the following: |
115aef16 | 42 | |
e69c1847 DM |
43 | * Complete operating system (Debian Linux, 64-bit) |
44 | ||
7f7446cf | 45 | * The {pve} installer, which partitions the local disk(s) with ext4, XFS, |
520e3616 | 46 | BTRFS (technology preview), or ZFS and installs the operating system |
e69c1847 | 47 | |
9a6dc394 | 48 | * {pve} Linux kernel with KVM and LXC support |
e69c1847 | 49 | |
9a6dc394 TL |
50 | * Complete toolset for administering virtual machines, containers, the host |
51 | system, clusters and all necessary resources | |
e69c1847 | 52 | |
32caab0e | 53 | * Web-based management interface |
115aef16 | 54 | |
520e3616 CH |
55 | NOTE: All existing data on the selected drives will be removed during the |
56 | installation process. The installer does not add boot menu entries for other | |
57 | operating systems. | |
078924cd | 58 | |
44ea3fd6 TL |
59 | Please insert the xref:installation_prepare_media[prepared installation media] |
60 | (for example, USB flash drive or CD-ROM) and boot from it. | |
61 | ||
62 | TIP: Make sure that booting from the installation medium (for example, USB) is | |
3a175eaa AZ |
63 | enabled in your server's firmware settings. Secure boot needs to be disabled |
64 | when booting an installer prior to {pve} version 8.1. | |
2c6fed66 | 65 | |
1ff5e4e8 | 66 | [thumbnail="screenshot/pve-grub-menu.png"] |
2d99ce9b | 67 | |
520e3616 CH |
68 | After choosing the correct entry (for example, 'Boot from USB') the {pve} menu |
69 | will be displayed, and one of the following options can be selected: | |
d91f8c1e | 70 | |
0c6bf9f5 | 71 | Install {pve} (Graphical):: |
d91f8c1e | 72 | |
32caab0e | 73 | Starts the normal installation. |
d91f8c1e | 74 | |
32caab0e AL |
75 | TIP: It's possible to use the installation wizard with a keyboard only. Buttons |
76 | can be clicked by pressing the `ALT` key combined with the underlined character | |
77 | from the respective button. For example, `ALT + N` to press a `Next` button. | |
1a5554fc | 78 | |
6452603e | 79 | Install {pve} (Terminal UI):: |
0c6bf9f5 | 80 | |
520e3616 | 81 | Starts the terminal-mode installation wizard. It provides the same overall |
0c6bf9f5 CH |
82 | installation experience as the graphical installer, but has generally better |
83 | compatibility with very old and very new hardware. | |
84 | ||
2a2e180c CH |
85 | Install {pve} (Terminal UI, Serial Console):: |
86 | ||
87 | Starts the terminal-mode installation wizard, additionally setting up the Linux | |
88 | kernel to use the (first) serial port of the machine for in- and output. This | |
89 | can be used if the machine is completely headless and only has a serial console | |
90 | available. | |
91 | ||
8668bfdf | 92 | [thumbnail="screenshot/pve-tui-installer.png"] |
38df5426 | 93 | |
8668bfdf TL |
94 | Both modes use the same code base for the actual installation process to |
95 | benefit from more than a decade of bug fixes and ensure feature parity. | |
96 | ||
6452603e | 97 | TIP: The 'Terminal UI' option can be used in case the graphical installer does |
eb638de4 CH |
98 | not work correctly, due to e.g. driver issues. See also |
99 | xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter]. | |
0c6bf9f5 | 100 | |
6452603e | 101 | Advanced Options: Install {pve} (Graphical, Debug Mode):: |
d91f8c1e | 102 | |
32caab0e AL |
103 | Starts the installation in debug mode. A console will be opened at several |
104 | installation steps. This helps to debug the situation if something goes wrong. | |
8dc994f7 TL |
105 | To exit a debug console, press `CTRL-D`. This option can be used to boot a live |
106 | system with all basic tools available. You can use it, for example, to | |
107 | xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the | |
108 | xref:sysboot[bootloader] for an existing {pve} setup. | |
d91f8c1e | 109 | |
6452603e | 110 | Advanced Options: Install {pve} (Terminal UI, Debug Mode):: |
0c6bf9f5 CH |
111 | |
112 | Same as the graphical debug mode, but preparing the system to run the | |
6452603e | 113 | terminal-based installer instead. |
0c6bf9f5 | 114 | |
6452603e | 115 | Advanced Options: Install {pve} (Serial Console Debug Mode):: |
0c6bf9f5 | 116 | |
6452603e CH |
117 | Same the terminal-based debug mode, but additionally sets up the Linux kernel to |
118 | use the (first) serial port of the machine for in- and output. | |
0c6bf9f5 | 119 | |
7e5ca633 | 120 | Advanced Options: Rescue Boot:: |
d91f8c1e | 121 | |
32caab0e AL |
122 | With this option you can boot an existing installation. It searches all attached |
123 | hard disks. If it finds an existing installation, it boots directly into that | |
124 | disk using the Linux kernel from the ISO. This can be useful if there are | |
7c73a209 CH |
125 | problems with the bootloader (GRUB/`systemd-boot`) or the BIOS/UEFI is unable to |
126 | read the boot block from the disk. | |
d91f8c1e | 127 | |
0c6bf9f5 | 128 | Advanced Options: Test Memory (memtest86+):: |
d91f8c1e | 129 | |
32caab0e | 130 | Runs `memtest86+`. This is useful to check if the memory is functional and free |
b0e1acde CH |
131 | of errors. Secure Boot must be turned off in the UEFI firmware setup utility to |
132 | run this option. | |
d91f8c1e | 133 | |
520e3616 CH |
134 | You normally select *Install {pve} (Graphical)* to start the installation. |
135 | ||
1ff5e4e8 | 136 | [thumbnail="screenshot/pve-select-target-disk.png"] |
2d99ce9b | 137 | |
520e3616 CH |
138 | The first step is to read our EULA (End User License Agreement). Following this, |
139 | you can select the target hard disk(s) for the installation. | |
140 | ||
141 | CAUTION: By default, the whole server is used and all existing data is removed. | |
142 | Make sure there is no important data on the server before proceeding with the | |
143 | installation. | |
d91f8c1e | 144 | |
520e3616 CH |
145 | The `Options` button lets you select the target file system, which |
146 | defaults to `ext4`. The installer uses LVM if you select | |
147 | `ext4` or `xfs` as a file system, and offers additional options to | |
148 | restrict LVM space (see xref:advanced_lvm_options[below]). | |
32caab0e | 149 | |
520e3616 CH |
150 | {pve} can also be installed on ZFS. As ZFS offers several software RAID levels, |
151 | this is an option for systems that don't have a hardware RAID controller. The | |
152 | target disks must be selected in the `Options` dialog. More ZFS specific | |
153 | settings can be changed under xref:advanced_zfs_options[`Advanced Options`]. | |
32caab0e AL |
154 | |
155 | WARNING: ZFS on top of any hardware RAID is not supported and can result in data | |
156 | loss. | |
d91f8c1e | 157 | |
d7c14bfd | 158 | [thumbnail="screenshot/pve-select-location.png"] |
2d99ce9b | 159 | |
520e3616 CH |
160 | The next page asks for basic configuration options like your location, time |
161 | zone, and keyboard layout. The location is used to select a nearby download | |
162 | server, in order to increase the speed of updates. The installer is usually able | |
163 | to auto-detect these settings, so you only need to change them in rare | |
164 | situations when auto-detection fails, or when you want to use a keyboard layout | |
165 | not commonly used in your country. | |
2d99ce9b | 166 | |
d7c14bfd | 167 | [thumbnail="screenshot/pve-set-password.png", float="left"] |
2d99ce9b | 168 | |
520e3616 | 169 | Next the password of the superuser (`root`) and an email address needs to be |
32caab0e AL |
170 | specified. The password must consist of at least 5 characters. It's highly |
171 | recommended to use a stronger password. Some guidelines are: | |
2d99ce9b | 172 | |
520e3616 | 173 | - Use a minimum password length of at least 12 characters. |
2d99ce9b | 174 | |
32caab0e | 175 | - Include lowercase and uppercase alphabetic characters, numbers, and symbols. |
2d99ce9b | 176 | |
32caab0e AL |
177 | - Avoid character repetition, keyboard patterns, common dictionary words, |
178 | letter or number sequences, usernames, relative or pet names, romantic links | |
179 | (current or past), and biographical information (for example ID numbers, | |
180 | ancestors' names or dates). | |
2d99ce9b | 181 | |
32caab0e AL |
182 | The email address is used to send notifications to the system administrator. |
183 | For example: | |
2d99ce9b DM |
184 | |
185 | - Information about available package updates. | |
186 | ||
520e3616 | 187 | - Error messages from periodic 'cron' jobs. |
2d99ce9b | 188 | |
7df6cb98 TL |
189 | [thumbnail="screenshot/pve-setup-network.png"] |
190 | ||
520e3616 CH |
191 | All those notification mails will be sent to the specified email address. |
192 | ||
193 | The last step is the network configuration. Network interfaces that are 'UP' | |
194 | show a filled circle in front of their name in the drop down menu. Please note | |
195 | that during installation you can either specify an IPv4 or IPv6 address, but not | |
196 | both. To configure a dual stack node, add additional IP addresses after the | |
197 | installation. | |
d91f8c1e | 198 | |
1ff5e4e8 | 199 | [thumbnail="screenshot/pve-installation.png", float="left"] |
2d99ce9b | 200 | |
520e3616 CH |
201 | The next step shows a summary of the previously selected options. Please |
202 | re-check every setting and use the `Previous` button if a setting needs to be | |
203 | changed. | |
204 | ||
205 | After clicking `Install`, the installer will begin to format the disks and copy | |
206 | packages to the target disk(s). Please wait until this step has finished; then | |
207 | remove the installation medium and restart your system. | |
d91f8c1e | 208 | |
7df6cb98 TL |
209 | [thumbnail="screenshot/pve-install-summary.png"] |
210 | ||
520e3616 CH |
211 | Copying the packages usually takes several minutes, mostly depending on the |
212 | speed of the installation medium and the target disk performance. | |
213 | ||
214 | When copying and setting up the packages has finished, you can reboot the | |
215 | server. This will be done automatically after a few seconds by default. | |
216 | ||
217 | .Installation Failure | |
218 | ||
b9a97ca1 | 219 | If the installation failed, check out specific errors on the second TTY |
520e3616 CH |
220 | ('CTRL + ALT + F2') and ensure that the systems meets the |
221 | xref:install_minimal_requirements[minimum requirements]. | |
222 | ||
223 | If the installation is still not working, look at the | |
224 | xref:getting_help[how to get help chapter]. | |
225 | ||
226 | ||
227 | Accessing the Management Interface Post-Installation | |
228 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
229 | ||
230 | [thumbnail="screenshot/gui-login-window.png"] | |
231 | ||
232 | After a succesful installation and reboot of the system you can use the {pve} | |
233 | web interface for further configuration. | |
234 | ||
235 | . Point your browser to the IP address given during the installation and port | |
236 | 8006, for example: https://youripaddress:8006 | |
237 | ||
238 | . Log in using the `root` (realm 'PAM') username and the password chosen during | |
239 | installation. | |
240 | ||
241 | . Upload your subscription key to gain access to the Enterprise repository. | |
242 | Otherwise, you will need to set up one of the public, less tested package | |
243 | repositories to get updates for security fixes, bug fixes, and new features. | |
244 | ||
245 | . Check the IP configuration and hostname. | |
7df6cb98 | 246 | |
520e3616 | 247 | . Check the timezone. |
fe6c04d5 | 248 | |
520e3616 | 249 | . Check your xref:chapter_pve_firewall[Firewall settings]. |
d91f8c1e DM |
250 | |
251 | [[advanced_lvm_options]] | |
5eba0743 | 252 | Advanced LVM Configuration Options |
6b5fc47b | 253 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
d91f8c1e | 254 | |
32caab0e | 255 | The installer creates a Volume Group (VG) called `pve`, and additional Logical |
67d2d94e CH |
256 | Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To |
257 | control the size of these volumes use: | |
d91f8c1e DM |
258 | |
259 | `hdsize`:: | |
260 | ||
32caab0e AL |
261 | Defines the total hard disk size to be used. This way you can reserve free space |
262 | on the hard disk for further partitioning (for example for an additional PV and | |
263 | VG on the same hard disk that can be used for LVM storage). | |
d91f8c1e DM |
264 | |
265 | `swapsize`:: | |
266 | ||
d3e2455a AL |
267 | Defines the size of the `swap` volume. The default is the size of the installed |
268 | memory, minimum 4 GB and maximum 8 GB. The resulting value cannot be greater | |
269 | than `hdsize/8`. | |
e8fe2b1b FG |
270 | + |
271 | NOTE: If set to `0`, no `swap` volume will be created. | |
d91f8c1e DM |
272 | |
273 | `maxroot`:: | |
274 | ||
fa281da6 TL |
275 | Defines the maximum size of the `root` volume, which stores the operation |
276 | system. The maximum limit of the `root` volume size is `hdsize/4`. | |
d91f8c1e DM |
277 | |
278 | `maxvz`:: | |
279 | ||
fa281da6 TL |
280 | Defines the maximum size of the `data` volume. The actual size of the `data` |
281 | volume is: | |
282 | + | |
283 | `datasize = hdsize - rootsize - swapsize - minfree` | |
284 | + | |
285 | Where `datasize` cannot be bigger than `maxvz`. | |
e8fe2b1b | 286 | + |
32caab0e AL |
287 | NOTE: In case of LVM thin, the `data` pool will only be created if `datasize` is |
288 | bigger than 4GB. | |
e8fe2b1b FG |
289 | + |
290 | NOTE: If set to `0`, no `data` volume will be created and the storage | |
291 | configuration will be adapted accordingly. | |
d91f8c1e DM |
292 | |
293 | `minfree`:: | |
294 | ||
67d2d94e | 295 | Defines the amount of free space that should be left in the LVM volume group |
93f1aa5d | 296 | `pve`. With more than 128GB storage available, the default is 16GB, otherwise |
67d2d94e | 297 | `hdsize/8` will be used. |
d91f8c1e | 298 | + |
32caab0e AL |
299 | NOTE: LVM requires free space in the VG for snapshot creation (not required for |
300 | lvmthin snapshots). | |
d91f8c1e | 301 | |
71280de0 SI |
302 | [[advanced_zfs_options]] |
303 | Advanced ZFS Configuration Options | |
304 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
8cfa5e4c CH |
305 | The installer creates the ZFS pool `rpool`, if ZFS is used. No swap space is |
306 | created but you can reserve some unpartitioned space on the install disks for | |
307 | swap. You can also create a swap zvol after the installation, although this can | |
308 | lead to problems (see xref:zfs_swap[ZFS swap notes]). | |
71280de0 SI |
309 | |
310 | `ashift`:: | |
311 | ||
32caab0e AL |
312 | Defines the `ashift` value for the created pool. The `ashift` needs to be set at |
313 | least to the sector-size of the underlying disks (2 to the power of `ashift` is | |
314 | the sector-size), or any disk which might be put in the pool (for example the | |
315 | replacement of a defective disk). | |
71280de0 SI |
316 | |
317 | `compress`:: | |
318 | ||
319 | Defines whether compression is enabled for `rpool`. | |
320 | ||
321 | `checksum`:: | |
322 | ||
323 | Defines which checksumming algorithm should be used for `rpool`. | |
324 | ||
325 | `copies`:: | |
326 | ||
327 | Defines the `copies` parameter for `rpool`. Check the `zfs(8)` manpage for the | |
328 | semantics, and why this does not replace redundancy on disk-level. | |
329 | ||
64b28d74 CH |
330 | `ARC max size`:: |
331 | ||
332 | Defines the maximum size the ARC can grow to and thus limits the amount of | |
333 | memory ZFS will use. See also the section on | |
334 | xref:sysadmin_zfs_limit_memory_usage[how to limit ZFS memory usage] for more | |
335 | details. | |
336 | ||
71280de0 SI |
337 | `hdsize`:: |
338 | ||
32caab0e | 339 | Defines the total hard disk size to be used. This is useful to save free space |
5f318cc0 | 340 | on the hard disk(s) for further partitioning (for example to create a |
32caab0e AL |
341 | swap-partition). `hdsize` is only honored for bootable disks, that is only the |
342 | first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123]. | |
71280de0 | 343 | |
d91f8c1e DM |
344 | |
345 | ZFS Performance Tips | |
6b5fc47b | 346 | ~~~~~~~~~~~~~~~~~~~~ |
d91f8c1e | 347 | |
32caab0e AL |
348 | ZFS works best with a lot of memory. If you intend to use ZFS make sure to have |
349 | enough RAM available for it. A good calculation is 4GB plus 1GB RAM for each TB | |
cdf58596 | 350 | RAW disk space. |
d91f8c1e | 351 | |
32caab0e AL |
352 | ZFS can use a dedicated drive as write cache, called the ZFS Intent Log (ZIL). |
353 | Use a fast drive (SSD) for it. It can be added after installation with the | |
354 | following command: | |
d91f8c1e | 355 | |
32caab0e AL |
356 | ---- |
357 | # zpool add <pool-name> log </dev/path_to_fast_ssd> | |
358 | ---- | |
078924cd | 359 | |
eb638de4 | 360 | [[nomodeset_kernel_param]] |
83a43f6e CH |
361 | Adding the `nomodeset` Kernel Parameter |
362 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
363 | ||
364 | Problems may arise on very old or very new hardware due to graphics drivers. If | |
eb638de4 CH |
365 | the installation hangs during boot, you can try adding the `nomodeset` |
366 | parameter. This prevents the Linux kernel from loading any graphics drivers and | |
367 | forces it to continue using the BIOS/UEFI-provided framebuffer. | |
83a43f6e CH |
368 | |
369 | On the {pve} bootloader menu, navigate to 'Install {pve} (Terminal UI)' and | |
370 | press `e` to edit the entry. Using the arrow keys, navigate to the line starting | |
371 | with `linux`, move the cursor to the end of that line and add the | |
372 | parameter `nomodeset`, separated by a space from the pre-existing last | |
373 | parameter. | |
374 | ||
375 | Then press `Ctrl-X` or `F10` to boot the configuration. | |
376 | ||
e0695f41 AL |
377 | [[installation_unattended]] |
378 | Unattended Installation | |
379 | ----------------------- | |
380 | ||
381 | It is possible to install {pve} automatically in an unattended manner. This | |
382 | enables you to fully automate the setup process on bare-metal. Once the | |
383 | installation is complete and the host has booted up, automation tools like | |
384 | Ansible can be used to further configure the installation. | |
385 | ||
386 | The necessary options for the installer must be provided in an answer file. This | |
387 | file allows the use of filter rules to determine which disks and network cards | |
388 | should be used. | |
389 | ||
390 | To use the automated installation, it is first necessary to prepare an | |
391 | installation ISO. | |
392 | https://pve.proxmox.com/wiki/Automated_Installation[Visit our wiki] for more | |
393 | details and information on the unattended installation. | |
394 | ||
078924cd DM |
395 | ifndef::wiki[] |
396 | ||
397 | Install {pve} on Debian | |
6b5fc47b | 398 | ----------------------- |
078924cd | 399 | |
b9a97ca1 | 400 | {pve} ships as a set of Debian packages and can be installed on top of a standard |
32caab0e AL |
401 | Debian installation. |
402 | xref:sysadmin_package_repositories[After configuring the repositories] you need | |
403 | to run the following commands: | |
078924cd | 404 | |
078924cd | 405 | ---- |
32caab0e AL |
406 | # apt-get update |
407 | # apt-get install proxmox-ve | |
078924cd DM |
408 | ---- |
409 | ||
32caab0e AL |
410 | Installing on top of an existing Debian installation looks easy, but it presumes |
411 | that the base system has been installed correctly and that you know how you want | |
412 | to configure and use the local storage. You also need to configure the network | |
413 | manually. | |
115aef16 | 414 | |
32caab0e | 415 | In general, this is not trivial, especially when LVM or ZFS is used. |
115aef16 | 416 | |
32caab0e | 417 | A detailed step by step how-to can be found on the |
def3e106 | 418 | {webwiki-url}Install_Proxmox_VE_on_Debian_12_Bookworm[wiki]. |
078924cd | 419 | |
078924cd | 420 | |
5c6cf7ac | 421 | endif::wiki[] |
078924cd | 422 | |
078924cd DM |
423 | ifdef::wiki[] |
424 | ||
425 | Video Tutorials | |
6b5fc47b | 426 | --------------- |
078924cd | 427 | |
e941eafc TL |
428 | See the list of all official tutorials on our |
429 | https://www.youtube.com/proxmoxve[{pve} YouTube Channel] | |
078924cd DM |
430 | |
431 | ||
432 | See Also | |
6b5fc47b | 433 | -------- |
078924cd | 434 | |
3b5f76b8 DJ |
435 | * link:/wiki/Prepare_Installation_Media[Prepare Installation Media] |
436 | ||
f3765da7 | 437 | * link:/wiki/Install_Proxmox_VE_on_Debian_12_Bookworm[Install Proxmox VE on Debian 12 Bookworm] |
3b5f76b8 | 438 | |
bc1c71d4 DM |
439 | * link:/wiki/System_Requirements[System Requirements] |
440 | ||
078924cd DM |
441 | * link:/wiki/Package_Repositories[Package Repositories] |
442 | ||
443 | * link:/wiki/Host_System_Administration[Host System Administration] | |
444 | ||
445 | * link:/wiki/Network_Configuration[Network Configuration] | |
446 | ||
e723066c DM |
447 | * link:/wiki/Installation:_Tips_and_Tricks[Installation: Tips and Tricks] |
448 | ||
078924cd | 449 | endif::wiki[] |