Debian VM creation

You can start creating VMs in your Proxmox VE server

Your Proxmox VE system is now configured well enough for you to start creating the virtual machines you require in it. This chapter will show you how to create a rather generic VM with Debian. This Debian VM will be the base over which you will build, in the following chapters, a more specialized VM template for your K3s cluster’s nodes.

Preparing the Debian ISO image

Since the operative system chosen to build the VMs is Debian Linux, first you need to get its ISO and store it in your Proxmox VE server.

Obtaining the latest stable Debian ISO image

At the time of writing this, the latest stable version of Debian is 13.0.0 “trixie”.

You can find the net install version of the ISO for the latest Debian version right at the Debian project’s webpage:

After clicking on that big Download button, your browser should start downloading the debian-13.0.0-amd64-netinst.iso file.

Storing the ISO image in the Proxmox VE platform

Proxmox VE needs that ISO image saved in the proper storage space it has available to be able to use it. Therefore, you need to upload the debian-13.0.0-amd64-netinst.iso file to the storage space you configured to hold such files, the one called hdd_templates:

1. Open the web console and unfold the tree of available storages under your pve node. Click on hdd_templates to reach its Summary page:

   

2. Click on the ISO Images tab to see the page of available ISO images:

   

   It appears empty at this point.

3. Click on the Upload button to raise the dialog below:

   

   Note

   Ensure having enough free storage available in your Proxmox VE’s root filesystem before uploading files
   Notice the warning about where Proxmox VE temporarily stores the file you upload before moving it to its definitive place. The /var/tmp/ path lays in the root filesystem of your PVE server, so be sure of having enough room in it or the upload will fail.

4. Click on Select File, find and select your debian-13.0.0-amd64-netinst.iso file in your computer, then click on Upload. The same dialog will show the upload progress:

   

   When the upload is finished, Proxmox VE shows you another dialog with the result of the task that moves the ISO file from the /var/tmp/ PVE system path to the hdd_templates storage:

   

5. Close the Task viewer dialog to return to the ISO Images page. See that the list now shows your newly uploaded Debian ISO image:

   

   Notice how the ISO is only identified by its file name. Sometimes ISOs do not have detailed names like the one for the Debian distribution. In those cases, give the ISOs you upload meaningful and unique names to tell them apart.

6. Finally, you can check out in the hdd_templates storage’s Summary how much space you have left (Usage field):

   

Now you only have one ISO image but, over time, you may accumulate a number of them. Be mindful of the free space you have left, and prune old images or container templates you are not using anymore.

Building a Debian virtual machine

This section covers how to create a basic and lean Debian VM, then how to turn it into a VM template.

Setting up a new virtual machine

First, you need to create and configure a new VM:

1. Click on the Create VM button found at the web console’s top right:

   

2. The Create: Virtual Machine window appears, opened at the General tab:

   

   From it, only worry about the following parameters:

   • Node
     In a cluster with several nodes you would need to choose where to put this VM. Since you only have one standalone node, just leave the default pve value.

   • VM ID
     A numerical identifier for the VM.

     Note

     Proxmox VE does not allow IDs lower than 100.

   • Name
     This field must be a valid DNS name, like debiantpl or something longer such as debiantpl.homelab.cloud.

     Note

     This Name field is not properly described by the official documentation
     The official Proxmox VE says that this name is a free form text string you can use to describe the VM, which contradicts what the web console actually validates as correct.

   • Resource Pool
     Here you can indicate to which pool of resources (you have none defined at this point) you want to make this VM a member of.

   The only value you really need to set here is the name, which in this case it could be debiantpl (for Debian Template):

   

3. Click on the Next button to reach the OS tab:

   

   In this form, you only have to choose the Debian ISO image you uploaded before. The Guest OS options are already properly set up for the kind of OS (a Linux distribution) you are going to install in this VM.

   Therefore, be sure of having the Use CD/DVD disc image file option enabled, then select the proper Storage (you should only see here the hdd_templates one) and ISO image (you just have one ISO right now):

   

4. The next tab to go to is System:

   

   Here, only tick the Qemu Agent checkbox and leave the rest with their default values:

   

   The QEMU agent “lets Proxmox VE know that it can use its features to show some more information, and complete some actions (for example, shutdown or snapshots) more intelligently”.

5. Hit on Next to advance to the Disks tab:

   

   In this step you have a form in which you can add several storage drives to your VM, but there are certain parameters that you need to see to create a virtual SSD drive. Enable the Advanced checkbox at the bottom of this window to see some extra parameters shown highlighted in the next snapshot:

   Note

   Not all tabs of the Create: Virtual Machine window have advanced options
   Although the Advanced checkbox appears in all the steps of this wizard, not all of those steps have advanced parameters to offer.

   

   From the many parameters showing now in this form, just pay attention to the following ones:

   • Storage
     Here you must choose on which storage you will place the disk image of this VM. At this point, in the list you can see only the thinpools created previously.

   • Disk size (GiB)
     How big you want the main disk for this VM, in gibibytes.

   • Discard
     Since this drive will be put on a thin provisioned storage, you can enable this option to make this drive’s image get shrunk when space is marked as freed after removing files within the VM.

   • SSD emulation
     If your storage is on an SSD drive, (like the ssd_disks thinpool), you can turn this on.

   • IO thread
     With this option enabled, IO activity will have its own CPU thread in the VM, which could improve the VM’s performance and also sets the SCSI Controller of the drive to VirtIO SCSI single.

   • Async IO
     The official documentation does not explain this value, but it can be summarized as the way to choose which method to use for asynchronous IO.

     Note

     Know more about the async IO property in this Proxmox Forum thread.

   Important

   The Bandwidth tab allows you to adjust the read/write capabilities of the storage drive
   Only adjust the bandwidth options if you are really sure about how to set them up.

   Knowing all this, choose the ssd_disks thinpool as Storage, put a small number as Disk Size (such as 10 GiB), and ensure to enable the Discard and SSD emulation options. Leave the IO thread option enabled (as it is by default), and do not change the default value already set in the Async IO parameter. Do not change any of the remaining parameters in this dialog:

   

   This way, you have configured the scsi0 drive you see listed in the column at the window’s left. If you want to add more drives, click on the Add button and a new drive will be added with default values.

6. The next tab to fill is CPU. Since you have enabled the Advanced checkbox in the previous Disks tab, you already see the advanced parameters of this and following steps right away:

   

   The parameters on this tab are very dependant on the real capabilities of your host’s CPU. The main parameters you have to care about at this point are:

   • Sockets
     A way of saying how many CPUs you want to assign to this VM. Just leave it with the default value (1).

   • Cores
     How many cores you want to give to this VM. When unsure on how many to assign, just put 2 here.

     Important

     Never enter here a number greater than the real cores count in your CPU
     Otherwise, Proxmox VE will not start your VM.

   • Type
     This indicates the type of CPU you want to emulate, and the closer it is to the real CPU running your system the better. There is a type host which makes the VM’s CPU have exactly the same flags as the real CPU running your Proxmox VE platform, but VMs with that host CPU type will only run on CPUs that include the same flags. So, if you migrated such VM to a new Proxmox VE platform that runs on a CPU lacking certain flags expected by the VM, the VM will not run there.

   • Enable NUMA
     If your host supports NUMA, enable this option.

   • Extra CPU Flags
     Flags to enable special CPU options on your VM. Only enable the ones actually available in the CPU Type you chose, otherwise the VM will not run. If you choose the type Host, you can see the flags available in your real CPU in the /proc/cpuinfo file within your Proxmox VE host:

     $ less /proc/cpuinfo

     This file lists the specifications of each core on your CPU. For instance, the first core (called processor in the file) of this guide’s Proxmox VE host is detailed as follows:

     processor       : 0
     vendor_id       : GenuineIntel
     cpu family      : 6
     model           : 55
     model name      : Intel(R) Celeron(R) CPU  J1900  @ 1.99GHz
     stepping        : 8
     microcode       : 0x838
     cpu MHz         : 2211.488
     cache size      : 1024 KB
     physical id     : 0
     siblings        : 4
     core id         : 0
     cpu cores       : 4
     apicid          : 0
     initial apicid  : 0
     fpu             : yes
     fpu_exception   : yes
     cpuid level     : 11
     wp              : yes
     flags           : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall nx rdtscp lm constant_tsc arch_perfmon pebs bts rep_good nopl xtopology tsc_reliable nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq dtes64 monitor ds_cpl vmx est tm2 ssse3 cx16 xtpr pdcm sse4_1 sse4_2 movbe popcnt tsc_deadline_timer rdrand lahf_lm 3dnowprefetch epb pti ibrs ibpb stibp tpr_shadow flexpriority ept vpid tsc_adjust smep erms dtherm ida arat vnmi md_clear
     vmx flags       : vnmi preemption_timer invvpid ept_x_only flexpriority tsc_offset vtpr mtf vapic ept vpid unrestricted_guest
     bugs            : cpu_meltdown spectre_v1 spectre_v2 mds msbds_only mmio_unknown
     bogomips        : 4000.00
     clflush size    : 64
     cache_alignment : 64
     address sizes   : 36 bits physical, 48 bits virtual
     power management:

     The flags available in the CPU are listed on the flags, vmx flags and bugs lists.

   Being aware of the capabilities of the real CPU used to run the Proxmox VE VM used in this guide, this form is filled like this:

   

7. The next tab is Memory, with its advanced parameters already shown:

   

   The parameters to set in this dialog are:

   • Memory (MiB)
     The maximum amount of RAM this VM will be allowed to use.

   • Minimum memory (MiB)
     The minimum amount of RAM Proxmox VE must guarantee for this VM.

   If the Minimum memory is a different (thus lower) value than the Memory one, Proxmox VE will use Automatic Memory Allocation to dynamically balance the use of the host RAM among the VMs you may have in your system, which you can also configure with the Shares attribute in this form. Better check the documentation to understand how Proxmox VE handles the VMs’ memory.

   

   With the arrangement above, the VM will start with 1 GiB and will be able to only take up to 2 GiB from the host’s available RAM.

8. The next tab to go to is Network, which also has advanced parameters:

   

   Notice how the Bridge parameter is set by default with the vmbr0 Linux bridge. You will come back to this parameter later but, for now, you do not need to configure anything in this step, the default values are correct for this Debian template VM.

9. The last tab to get into is Confirm:

   

   Here you can give a final look to the configuration you have assigned to your new VM before you create it. If you want to readjust something, just click on the proper tab or press Back to reach the step you want to change.

   Also notice the Start after created check. Do NOT enable it, since it makes Proxmox VE boot up your new VM right after its creation, something you do not want at this point.

10. Click on Finish and the creation should proceed. Check the Tasks log at the bottom of your web console to see its progress:

    

    Notice how the new VM appears in the Server View tree of your PVE node. Click on it to see its Summary view as shown in the capture above.

The configuration file for the new VM is stored at /etc/pve/nodes/pve/qemu-server (notice that it is related to the pve node) as [VM ID].conf. For this new VM with the VM ID 100, the file is /etc/pve/nodes/pve/qemu-server/100.conf:

agent: 1
balloon: 1024
boot: order=scsi0;ide2;net0
cores: 2
cpu: host
ide2: hdd_templates:iso/debian-13.0.0-amd64-netinst.iso,media=cdrom,size=754M
memory: 2048
meta: creation-qemu=10.0.2,ctime=1756890694
name: debiantpl
net0: virtio=BC:24:11:3E:B9:39,bridge=vmbr0,firewall=1
numa: 0
ostype: l26
scsi0: ssd_disks:vm-100-disk-0,discard=on,iothread=1,size=10G,ssd=1
scsihw: virtio-scsi-single
smbios1: uuid=8fce9b8d-d716-4e7b-9817-3d727b40eb9f
sockets: 1
vmgenid: 08b95c71-2feb-4338-8970-c3cfba8a6e94

Adding an extra network device to the new VM

In the VM creation wizard, Proxmox VE does not allow you to configure more than one network device. To add an extra network device in your VM, you have to do it after you have created the VM in Proxmox VE. And why the extra network device? To allow your future K3s cluster’s nodes to communicate directly with each other through the other Linux bridge you already created for this exact purpose. Keep on reading to learn how to add that extra network device to your new VM:

1. Go to the Hardware tab of your new VM:

   

2. Click on Add to see the list of devices you can aggregate to the VM, then choose Network Device:

   

3. The Network window that appears is exactly the same as the Network tab you saw while creating the VM:

   

   Notice that the Advanced options are also enabled, probably because the Proxmox VE web administration remembers that check as enabled from the creation wizard. Here you have to adjust only two parameters:

   • Bridge
     You must set the vmbr1 bridge.

   • Firewall
     Since this network device is strictly meant for internal networking, you do not need the firewall active here. Uncheck this option.

   

4. Click on Add and see how the new network device appears immediately as net1 at the end of your VM’s hardware list:

   

Installing Debian on the new VM

At this point, your new VM has the minimal virtual hardware setup you need for installing Debian in it:

1. Go back to the Summary tab of your new VM so you can see its status and performance statistics, then press the Start button to start the VM up:

   

   Right after starting the VM, click on the >_ Console button to raise a noVNC shell window.

2. In the noVCN shell window, you should end up seeing the Debian installer boot menu:

   

3. In this menu, you must choose the Install option to run the installation of Debian in text mode:

   

   It will take a few seconds to load the next step’s screen.

4. The next screen asks you about what language you want to use in the installation process and apply to the installed system:

   

   Just choose whatever suits you and press Enter.

5. The following step is about your geographical location. This will determine your VM’s timezone and locale:

   

   Again, highlight whatever suits you and press Enter.

6. If you choose an unexpected combination of language and location, the installer will ask you about what locale to apply on your system:

   

   Oddly enough, it only offers the options shown in the screenshot above. In case of doubt, just stick with the default United States - en_US.UTF-8 option.

7. Next, you have to choose your preferred keyboard configuration:

   

8. At this point it will show some progress bars while the installer retrieves additional components and scans the VM’s hardware:

   

9. After a few seconds, you get to the screen for configuring the network:

   

   Since this VM has two virtual Ethernet network cards, the installer must know which one to use as the primary network device. Leave the default option (the card with the lowest ens## number, like the ens18 in the snapshot) and press Enter.

10. Next, you see how the installer tries to setup the network in a few progress bars:

    

11. If the previous network autosetup process is successful, you end up in the following screen:

    

    In the text box, type in the hostname for this system, bearing in mind that this VM will become just a template to build others. Preferably, input the same name you used previously in the creation of the VM, which in this guide is debiantpl.

12. In the next step you have to specify a domain name:

    

    Here use the same one you set for your Proxmox VE system, which in this guide is homelab.cloud.

13. The following screen is about setting up the password for the root user:

    

    Since this VM is going to be just a template, there is no need here for you to type a difficult or long password.

14. The installer will ask you to confirm the root password:

    

15. The next step is about creating a new user that you should use instead of the root one:

    

    In this screen you are expected to type the new user’s full name, but since this is going to be your administrative one, input something more generic like System Manager for instance.

16. The following screen is about typing a username for the new user:

    

    By default, the installer will take the first word you set as the user’s full name and use it (in lowercase) as username. In this guide, this user is called mgrsys, following the same criteria used for creating the alternative manager user for the Proxmox VE host.

17. On this step you input the password for this new administrative user. Again, since this VM is going to be just a template, do not enter a complex password here:

    

18. You have to confirm the new user’s password:

    

19. This step is just about setting up the clock of this VM. First, the Debian installer will try to find a proper time server:

    

    Then, the installer may or may not ask your specific timezone within the country you picked earlier:

    

20. After a few more loading bars, you advance to the step for disk partitioning:

    

    Be sure of choosing the SECOND guided option to give the VM’s disk a more flexible partition structure with the LVM system, like the one you have in your Proxmox VE host:

    

21. The following screen is about choosing the storage drive to partition:

    

    There is only one disk attached to this VM, so there is no other option but the one shown.

22. Next, the installer asks you which partition schema you want to apply:

    

    This VM is going to be a template for servers, so you should never need to mount a separate partition for the home directory. Something else could be said about directories like var or srv, or even the swap, whose contents can potentially grow notably. But, since you can increase the size of the VM’s storage easily from Proxmox VE, just leave the default highlighted option and press Enter.

23. The next screen is the confirmation of the disk partitioning you have setup in the previous steps:

    

    If you are sure that the partition setup is what you wanted, highlight Yes and press Enter.

24. The following step asks you about the size assigned to the LVM group in which the system partitions are going to be created:

    

    Unless you know better, just stick with the default value and move on.

25. The installer applies the partition scheme selected and, after seeing some more fast progress windows, you reach the disk partitioning final confirmation screen:

    

    Choose Yes to allow the installer to finally write the changes on the storage.

26. After the partitioning is finished, the progress bar for the base system installation appears:

    

    The Debian installer needs a bit of time to finish this task.

27. When the base system is installed, the following dialog appears:

    

    Since you do not have any additional media to use, just answer No to this dialog.

28. The following step is about setting the right mirror servers location for your apt configuration:

    

    By default, the option highlighted will be the same country you chose at the beginning of this installation. Pick the country that suits you best.

29. The next screen is about choosing a concrete mirror server for your apt settings:

    

    Stick with the default option, or change it if you identify a better alternative for you in the list.

30. A window arises asking you to input your HTTP proxy information, if your PVE node happens to be connecting through one:

    

    In this guide it is assumed that you are not using a proxy, so that field should be left blank.

31. The installer takes a moment to configure the VM’s apt system:

    

32. When the apt configuration has finished, the installer asks you the following question about allowing a script to get some usage statistics of packages on your system:

    

    Choose whatever you like here, although bear in mind that the security restrictions you will have to apply in a later chapter to this Debian VM system may end blocking that script’s functionality.

33. After another loading bar, you reach the Software selection screen:

    

    You can see here that, by default, the installer is setting the VM to be a graphical environment. Since your VM is going to be the basic template for server VMs, you only need enabled the two last options (SSH server and standard system utilities). Change the options here to make them look like below and then press Continue:

    

34. Another progress windows shows up and the installer will proceed with the remainder of the software installation process:

    

35. After finishing the software installation, the installer asks you if you want to install the GRUB boot loader in the VM’s primary storage drive:

    

    The default Yes option is the correct one, so just press Enter on this screen.

36. Next, the installer asks you on which drive you want to install GRUB:

    

    Highlight the /dev/sda option and press Enter to continue the process:

    

37. After configuring the GRUB boot loader, the installer performs the remaining necessary tasks to finish the Debian installation:

    

38. After the installation has finished, the installer warns you about removing the media you used to launch the whole procedure:

    Warning

    Keep calm, DO NOT press Enter yet and read the next steps
    If you Continue, the VM will reboot and, if the installer media is still in place, the installer will boot up again.

    

39. Go back to your Proxmox VE web console, and open the Hardware tab of your VM. Then, choose the CD/DVD Drive item and press the Edit button (or just double click on the item):

    

40. See there the Edit window for the CD/DVD Drive you chose:

    

    Here, choose the Do not use any media option and click on OK.

    

41. Back in the Hardware screen, you should see how the CD/DVD Drive is now set to none:

    

    Important

    This does not mean that the change has been applied to the still running VM
    Usually, changes like these will require a reboot of the VM.

42. Now that the VM’s CD/DVD drive is configured to be empty, you can go back to the noVNC shell and press on Enter to finish the Debian installation. If everything goes as it should, the VM should reboot into the GRUB screen of your newly installed Debian system:

    

43. Press Enter with the default highlighted option or allow the timer to reach 0. Then, after the usual system booting shell output, you should reach the login prompt:

    

44. As a final verification, login either with root or with mgrsys to check that they work as expected.

Note about the VM’s Boot Order option

Go to the Options tab of your new Debian VM:

In the capture above, you can see highlighted the Boot Order list currently enabled in this VM. If you press on the Edit button, you can edit this Boot Order list:

Notice how PVE has already enabled the bootable hardware devices (hard disk, CD/DVD drive and network device) that were configured in the VM creation process. Also see how the network device added later, net1, is NOT enabled by default.

Relevant system paths

Directories

• /etc/pve
• /etc/pve/nodes/pve/qemu-server

Files

• /etc/pve/user.cfg
• /etc/pve/nodes/pve/qemu-server/100.cfg

References

About installing Debian

• HowtoForge. How to Install a Debian 12 (Bookworm) Minimal Server

Proxmox

• Proxmox VE Administration Guide

  • QEMU/KVM Virtual Machines

    • CPU
    • Memory
    • Network Device

  • User Management

    • Permission Management
      • Pools

• Proxmox. Forums. Proxmox Virtual Environment

  • Proxmox VE: Installation and configuration
    • Async IO Settings for Virtual Disks: Documentation? How to Set?

Contents related to virtualization

• Reddit. Proxmox. Best practices on setting up Proxmox on a new server
• Wikipedia. Non-uniform memory access

Storage measure units

• Wikipedia. Gigabyte
  • Definition. Base 2 (binary)