Bftcpa606: Created page with " = Running Containers on Proxmox VE = == A Procedural Tutorial for Administrators == == 1. Purpose == This tutorial explains the key concepts and procedures involved in running Linux containers on Proxmox Virtual Environment. After completing the tutorial, you should be able to: 1. Explain the difference between a container and a virtual machine. 2. Download a container operating-system template. 3. Create and configure an LXC co..."

2026-07-13T20:48:30Z

Created page with " = Running Containers on Proxmox VE = == A Procedural Tutorial for Administrators == == 1. Purpose == This tutorial explains the key concepts and procedures involved in running Linux containers on Proxmox Virtual Environment. After completing the tutorial, you should be able to: 1. Explain the difference between a container and a virtual machine. 2. Download a container operating-system template. 3. Create and configure an LXC co..."

New page

= Running Containers on Proxmox VE =

== A Procedural Tutorial for Administrators ==

== 1. Purpose ==
This tutorial explains the key concepts and procedures involved in running Linux containers on Proxmox Virtual Environment.

After completing the tutorial, you should be able to:

1. Explain the difference between a container and a virtual machine.

2. Download a container operating-system template.

3. Create and configure an LXC container.

4. Allocate CPU, memory, storage, and networking resources.

5. Start, stop, update, and troubleshoot a container.

6. Configure backups, snapshots, and firewall protection.

7. Decide whether an application should run in an LXC container, a virtual machine, or Docker.

== 2. Understand Proxmox Container Architecture ==
Proxmox VE supports two primary forms of virtualization:

• '''KVM virtual machines'''

• '''LXC containers'''

A KVM virtual machine emulates a complete computer and runs its own kernel. An LXC container shares the Proxmox host’s Linux kernel but maintains a separate user space, filesystem, processes, network configuration, and resource limits.

Proxmox containers are designed primarily as '''system containers'''. A system container behaves like a small Linux server. It can run services such as:

• Web servers

• Database servers

• DNS servers

• File-sharing services

• Monitoring systems

• Internal business applications

• Reverse proxies

• Development environments

The Proxmox Container Toolkit, accessed through the pct command, manages LXC containers and integrates them with Proxmox storage, networking, clustering, firewall, backup, and high-availability features.

=== Container versus virtual machine ===
{| class="wikitable"
| valign="top" |Consideration
| valign="top" |LXC container
| valign="top" |KVM virtual machine
|-
| valign="top" |Kernel
| valign="top" |Shares the Proxmox host kernel
| valign="top" |Uses its own kernel
|-
| valign="top" |Operating systems
| valign="top" |Linux only
| valign="top" |Linux, Windows, BSD, and others
|-
| valign="top" |Startup time
| valign="top" |Usually a few seconds
| valign="top" |Usually longer
|-
| valign="top" |Resource overhead
| valign="top" |Low
| valign="top" |Higher
|-
| valign="top" |Isolation
| valign="top" |Good, but less complete than a VM
| valign="top" |Stronger isolation
|-
| valign="top" |Kernel modules
| valign="top" |Controlled by the host
| valign="top" |Managed inside the VM
|-
| valign="top" |Hardware passthrough
| valign="top" |More complicated
| valign="top" |Generally more flexible
|-
| valign="top" |Best use
| valign="top" |Lightweight Linux services
| valign="top" |Strong isolation or non-Linux workloads
|}
Use a container when the workload is Linux-based, does not require its own kernel, and benefits from low overhead.

Use a virtual machine when the workload:

• Runs Windows or another non-Linux operating system.

• Requires a custom kernel.

• Requires stronger security isolation.

• Requires complicated hardware passthrough.

• Runs software that is not compatible with LXC restrictions.

• Will host untrusted users or untrusted code.

== 3. Understand System Containers and Application Containers ==
An LXC container in Proxmox normally represents an entire Linux operating-system environment. For example, one container might run Debian with Nginx, PHP, SSH, systemd, and scheduled tasks.

This differs from the common Docker model, in which each container usually runs a single application or service.

A useful way to distinguish them is:

• '''Proxmox LXC:''' a lightweight Linux server.

• '''Docker container:''' a packaged application process.

Current Proxmox documentation also describes support for creating LXC-based containers from Open Container Initiative images. However, application-container support is identified as a technology preview. For ordinary production administration, conventional Linux LXC templates remain the more established approach.

== 4. Prepare the Proxmox Host ==
Before creating a container, confirm that the Proxmox node has:

• Available memory

• Available CPU capacity

• Suitable storage

• A working Linux bridge

• Current system updates

• A configured backup destination

=== Step 1: Check the Proxmox version ===
Open the Proxmox shell and run:

bash

pveversion -v

=== Step 2: Install available updates ===
Use the Proxmox web interface:

1. Select the Proxmox node.

2. Select '''Updates'''.

3. Click '''Refresh'''.

4. Review the available packages.

5. Click '''Upgrade'''.

Alternatively, use the host shell:

bash

apt update

apt full-upgrade

Reboot the host when a kernel or other major system component has been updated:

bash

reboot

Do not install ordinary application workloads directly on the Proxmox host. Keep the host dedicated to virtualization, storage, networking, backup, and cluster management.

=== Step 3: Review available storage ===
In the web interface:

1. Select '''Datacenter'''.

2. Select '''Storage'''.

3. Review each storage target.

4. Confirm that at least one storage target permits '''Container''' content.

5. Confirm that storage is available for '''Container templates''' and '''Backup files'''.

Typical storage roles might be:
{| class="wikitable"
| valign="top" |Storage name
| valign="top" |Typical contents
|-
| valign="top" |local
| valign="top" |Templates, ISO images, backup files
|-
| valign="top" |local-lvm
| valign="top" |Container and VM disks
|-
| valign="top" |local-zfs
| valign="top" |Container and VM datasets
|-
| valign="top" |pbs
| valign="top" |Proxmox Backup Server backups
|-
| valign="top" |nfs-backup
| valign="top" |Backup files on network storage
|}

=== Step 4: Review the network bridge ===
In the web interface:

1. Select the Proxmox node.

2. Select '''System'''.

3. Select '''Network'''.

4. Identify the primary bridge, commonly named vmbr0.

5. Confirm that the bridge is connected to the correct physical network interface.

A container’s virtual network adapter normally connects to a Linux bridge. The bridge acts like a virtual Ethernet switch that connects the container to the physical network.

== 5. Download a Container Template ==
A container template is a compressed Linux filesystem used to create new containers.

=== Using the web interface ===
1. Select the storage that accepts container templates, commonly '''local'''.

2. Select '''CT Templates'''.

3. Click '''Templates'''.

4. Select a Linux distribution.

5. Click '''Download'''.

6. Wait for the download task to finish.

Common choices include Debian, Ubuntu, AlmaLinux, Rocky Linux, Fedora, and Alpine Linux.

=== Using the command line ===
bash

pveam available

pveam available | grep debian

pveam update

pveam download local debian-13-standard_13.1-1_amd64.tar.zst

pveam list local

The exact filename changes as templates are updated. Use the filename shown by pveam available.

== 6. Plan the Container ==
Before clicking '''Create CT''', record the planned configuration.
{| class="wikitable"
| valign="top" |Setting
| valign="top" |Example
|-
| valign="top" |Container ID
| valign="top" |110
|-
| valign="top" |Hostname
| valign="top" |web01
|-
| valign="top" |Operating system
| valign="top" |Debian
|-
| valign="top" |Privilege mode
| valign="top" |Unprivileged
|-
| valign="top" |CPU cores
| valign="top" |2
|-
| valign="top" |Memory
| valign="top" |2 GB
|-
| valign="top" |Swap
| valign="top" |512 MB
|-
| valign="top" |Root disk
| valign="top" |16 GB
|-
| valign="top" |Bridge
| valign="top" |vmbr0
|-
| valign="top" |IPv4 address
| valign="top" |192.168.10.110/24
|-
| valign="top" |Gateway
| valign="top" |192.168.10.1
|-
| valign="top" |DNS domain
| valign="top" |example.local
|-
| valign="top" |DNS server
| valign="top" |192.168.10.5
|-
| valign="top" |Start at boot
| valign="top" |Yes
|-
| valign="top" |Firewall
| valign="top" |Yes
|-
| valign="top" |Backup
| valign="top" |Nightly
|}
Choose a descriptive hostname. Avoid generic names such as server1 when a functional name such as proxy01, wiki01, or monitor01 would be clearer.

== 7. Choose Between Privileged and Unprivileged Containers ==

=== Unprivileged container ===
In an unprivileged container, root inside the container is mapped to a non-root user ID on the Proxmox host.

Advantages include better protection against container escape and reduced impact of many container-level security problems.

Disadvantages include more complicated permissions for bind mounts, device access, and some nested workloads.

=== Privileged container ===
In a privileged container, root inside the container corresponds more directly to root privileges on the host.

This can simplify device access, certain network appliances, filesystem mounts, and legacy applications, but it offers weaker isolation.

=== Recommended rule ===
Use an '''unprivileged container by default'''. Create a privileged container only when the workload has a documented technical requirement that cannot reasonably be met with an unprivileged container.

== 8. Create a Container Through the Web Interface ==

=== Step 1: Open the creation wizard ===
1. Log in to the Proxmox web interface.

2. Select the desired node.

3. Click '''Create CT'''.

=== Step 2: Complete the General page ===
Enter the node, CT ID, hostname, optional resource pool, root password, and SSH public key. Enable '''Unprivileged container''' unless there is a documented reason not to.

=== Step 3: Select the template ===
Choose the template storage and downloaded operating-system template.

=== Step 4: Configure the root disk ===
Choose the storage target and disk size.
{| class="wikitable"
| valign="top" |Workload
| valign="top" |Starting root disk
|-
| valign="top" |DNS or small utility
| valign="top" |4–8 GB
|-
| valign="top" |Reverse proxy
| valign="top" |8–16 GB
|-
| valign="top" |General Linux server
| valign="top" |16–32 GB
|-
| valign="top" |Database server
| valign="top" |32 GB or more
|-
| valign="top" |File or media service
| valign="top" |Separate data mount recommended
|}

=== Step 5: Allocate CPU resources ===
Set cores, CPU limit if needed, and CPU units. Start small and increase resources based on measured demand.

=== Step 6: Allocate memory ===
Set memory and swap.
{| class="wikitable"
| valign="top" |Workload
| valign="top" |Memory
|-
| valign="top" |Small DNS or proxy server
| valign="top" |512 MB–1 GB
|-
| valign="top" |General web application
| valign="top" |1–4 GB
|-
| valign="top" |Database server
| valign="top" |Based on workload
|-
| valign="top" |Monitoring platform
| valign="top" |2–8 GB or more
|}
Leave sufficient memory for the Proxmox host, ZFS ARC if applicable, other guests, and backup operations.

=== Step 7: Configure networking ===
Enter the interface name, bridge, VLAN tag if needed, IP configuration, gateway, firewall setting, and optional rate limit.

For DHCP:

text

IPv4: DHCP

For a static address:

text

IPv4/CIDR: 192.168.10.110/24

Gateway: 192.168.10.1

=== Step 8: Configure DNS ===
Specify the DNS search domain and DNS server addresses.

=== Step 9: Confirm the configuration ===
Review the settings, optionally enable '''Start after created''', and click '''Finish'''.

== 9. Create a Container from the Command Line ==
bash

pct create 110 \

local:vztmpl/debian-13-standard_13.1-1_amd64.tar.zst \

--hostname web01 \

--unprivileged 1 \

--cores 2 \

--memory 2048 \

--swap 512 \

--rootfs local-lvm:16 \

--net0 name=eth0,bridge=vmbr0,ip=192.168.10.110/24,gw=192.168.10.1,firewall=1 \

--nameserver 192.168.10.5 \

--searchdomain example.local \

--ssh-public-keys /root/.ssh/id_ed25519.pub \

--onboot 1

Display the container configuration:

bash

pct config 110

== 10. Start and Access the Container ==
bash

pct start 110

pct status 110

pct console 110

pct enter 110

pct list

Use exit to leave the container shell.

== 11. Perform the Initial Operating-System Configuration ==
For Debian or Ubuntu:

bash

apt update

apt full-upgrade -y

Set the timezone:

bash

timedatectl set-timezone America/Chicago

Create an administrative user:

bash

adduser administrator

usermod -aG sudo administrator

Install and enable SSH if required:

bash

apt install openssh-server

systemctl enable --now ssh

Recommended SSH settings after key-based access has been tested:

text

PermitRootLogin no

PasswordAuthentication no

PubkeyAuthentication yes

Restart SSH:

bash

systemctl restart ssh

Install basic tools as needed:

bash

apt install curl wget vim-nox nano htop ca-certificates gnupg unzip

== 12. Manage Container Resources ==
bash

pct set 110 --memory 4096

pct set 110 --swap 1024

pct set 110 --cores 4

pct set 110 --onboot 1

pct set 110 --startup order=20,up=30,down=60

Startup ordering is useful when one service depends on another.

== 13. Add Storage to a Container ==

=== Proxmox-managed mount point ===
bash

pct set 110 --mp0 local-lvm:50,mp=/srv/data,backup=1

=== Bind mount ===
bash

mkdir -p /srv/shared

pct set 110 --mp0 /srv/shared,mp=/mnt/shared

Bind mounts require careful planning for user-ID mappings, backups, and migration.

== 14. Understand User-ID Mapping ==
A common default mapping is conceptually similar to:
{| class="wikitable"
| valign="top" |Container ID
| valign="top" |Host ID
|-
| valign="top" |0
| valign="top" |100000
|-
| valign="top" |1
| valign="top" |100001
|-
| valign="top" |1000
| valign="top" |101000
|}
For example:

bash

chown 101000:101000 /srv/shared

cat /etc/subuid

cat /etc/subgid

Verify mappings before changing ownership.

== 15. Configure Networking After Creation ==
bash

pct config 110

pct set 110 --net0 name=eth0,bridge=vmbr0,ip=dhcp,firewall=1

pct set 110 --net0 name=eth0,bridge=vmbr0,ip=192.168.10.110/24,gw=192.168.10.1,firewall=1

pct set 110 --net0 name=eth0,bridge=vmbr0,tag=20,ip=192.168.20.110/24,gw=192.168.20.1,firewall=1

== 16. Configure the Proxmox Firewall ==
Enable and review the firewall at the Datacenter, node, container, and interface levels as appropriate.

Example policy:
{| class="wikitable"
| valign="top" |Direction
| valign="top" |Action
| valign="top" |Protocol/port
| valign="top" |Source
|-
| valign="top" |In
| valign="top" |Accept
| valign="top" |TCP 22
| valign="top" |Administration subnet
|-
| valign="top" |In
| valign="top" |Accept
| valign="top" |TCP 443
| valign="top" |Internal networks
|-
| valign="top" |In
| valign="top" |Drop
| valign="top" |All others
| valign="top" |Any
|-
| valign="top" |Out
| valign="top" |Accept
| valign="top" |Required traffic
| valign="top" |Any
|}
Always create and test management-access rules before applying a default-deny policy.

== 17. Back Up Containers ==
Create a manual backup:

bash

vzdump 110 --storage nfs-backup --mode snapshot --compress zstd

Backup modes include snapshot, suspend, and stop.

A basic retention plan might include seven daily backups, four weekly backups, and several monthly backups.

Periodically test restores by restoring under a temporary ID, attaching the container to an isolated network, starting it, and verifying the operating system, application, and data.

== 18. Use Snapshots Carefully ==
bash

pct snapshot 110 before-upgrade

pct listsnapshot 110

pct rollback 110 before-upgrade

pct delsnapshot 110 before-upgrade

Snapshots are short-term rollback tools, not backups.

== 19. Clone and Template Containers ==
Before cloning, remove or regenerate machine-specific information such as hostnames, IP addresses, SSH host keys, application node identifiers, monitoring IDs, and database replication identities.

Use full clones when the new container should be independent.

== 20. Monitor Container Performance ==
Useful commands include:

bash

top

htop

free -h

df -h

ip address

ss -tulpn

journalctl -p warning

Investigate CPU, memory, storage, networking, application, and host contention issues before simply adding resources.

== 21. Stop, Reboot, and Shut Down Containers Correctly ==
bash

pct shutdown 110

pct reboot 110

pct stop 110

pct status 110

Use pct stop only when graceful shutdown fails or immediate termination is necessary.

== 22. Troubleshoot a Container That Will Not Start ==
bash

pct start 110 --debug

pct config 110

pvesm status

journalctl -xe

journalctl -xe | grep 110

df -h

zpool status

zfs list

pvs

vgs

lvs

The container configuration is normally stored under:

text

/etc/pve/lxc/110.conf

== 23. Troubleshoot Network Connectivity ==
From the host:

bash

ping 192.168.10.110

pct config 110

Inside the container:

bash

ip address

ip route

cat /etc/resolv.conf

ping 192.168.10.1

ping 1.1.1.1

getent hosts example.com

curl -I <nowiki>https://example.com</nowiki>

Check the interface, IP address, gateway, external routing, DNS, VLAN, bridge, and firewall rules in that order.

== 24. Use Nesting Only When Required ==
bash

pct set 110 --features nesting=1

Nesting may be required for Docker, Podman, some build systems, and certain sandboxing tools. It expands access to kernel-related interfaces and can reduce isolation.

== 25. Decide How to Run Docker ==

=== Option 1: Docker in a virtual machine ===
text

Proxmox host

└── Linux virtual machine

   └── Docker Engine

   ├── Application container

   ├── Database container

   └── Proxy container

This is usually the safest general recommendation for production Docker deployments.

=== Option 2: Docker in an LXC container ===
text

Proxmox host

└── LXC system container

   └── Docker Engine

   └── Application containers

This uses fewer resources but adds complexity around nesting, storage drivers, networking, AppArmor, cgroups, and device access.

=== Option 3: Docker directly on the Proxmox host ===
This is generally discouraged because Docker can alter firewall behavior, bridges, packet-filtering rules, storage configuration, and upgrade behavior.

== 26. Apply Container Security Practices ==
1. Prefer unprivileged containers.

2. Keep Proxmox VE updated.

3. Keep container operating systems updated.

4. Use SSH keys instead of passwords.

5. Disable unnecessary services.

6. Restrict management access by network.

7. Enable appropriate firewall rules.

8. Avoid exposing the Proxmox interface directly to the Internet.

9. Use multifactor authentication for administrators.

10.    Back up container data.

11.    Test restores.

12.    Do not mount sensitive host directories into containers.

13.    Avoid unnecessary nesting.

14.    Avoid privileged containers unless technically required.

15.    Use separate containers for unrelated services.

16.    Monitor logs and resource usage.

17.    Use a VM for untrusted code or workloads requiring stronger isolation.

== 27. Maintain Containers ==

=== Weekly tasks ===
• Review failed Proxmox tasks.

• Review backup results.

• Check storage utilization.

• Review high CPU or memory usage.

• Check container service health.

=== Monthly tasks ===
• Install operating-system updates.

• Review firewall rules.

• Review user accounts and SSH keys.

• Review available disk space.

• Verify monitoring and alerts.

• Test at least one representative backup restore.

=== Quarterly tasks ===
• Review resource allocations.

• Remove obsolete snapshots.

• Review privileged containers.

• Review containers with nesting enabled.

• Review unsupported or end-of-life operating systems.

• Confirm documentation and recovery procedures.

== 28. Example Deployment: Create a Small Web Server ==
Use these example settings:
{| class="wikitable"
| valign="top" |Setting
| valign="top" |Value
|-
| valign="top" |CT ID
| valign="top" |120
|-
| valign="top" |Hostname
| valign="top" |web01
|-
| valign="top" |Template
| valign="top" |Current Debian template
|-
| valign="top" |Unprivileged
| valign="top" |Yes
|-
| valign="top" |Cores
| valign="top" |2
|-
| valign="top" |Memory
| valign="top" |1 GB
|-
| valign="top" |Swap
| valign="top" |512 MB
|-
| valign="top" |Root disk
| valign="top" |8 GB
|-
| valign="top" |IP address
| valign="top" |192.168.10.120/24
|-
| valign="top" |Gateway
| valign="top" |192.168.10.1
|-
| valign="top" |Bridge
| valign="top" |vmbr0
|-
| valign="top" |Start at boot
| valign="top" |Yes
|-
| valign="top" |Firewall
| valign="top" |Yes
|}
Then run:

bash

pct start 120

pct enter 120

apt update

apt full-upgrade -y

apt install nginx -y

systemctl enable --now nginx

systemctl status nginx

ss -tulpn | grep :80

curl <nowiki>http://127.0.0.1</nowiki>

Test from another computer by opening:

text

<nowiki>http://192.168.10.120</nowiki>

Configure firewall access, add the container to the backup schedule, and document its purpose, owner, IP address, and recovery procedure.

== 29. Essential pct Command Reference ==
{| class="wikitable"
| valign="top" |Task
| valign="top" |Command
|-
| valign="top" |List containers
| valign="top" |pct list
|-
| valign="top" |Show status
| valign="top" |pct status 110
|-
| valign="top" |Show configuration
| valign="top" |pct config 110
|-
| valign="top" |Start
| valign="top" |pct start 110
|-
| valign="top" |Graceful shutdown
| valign="top" |pct shutdown 110
|-
| valign="top" |Stop immediately
| valign="top" |pct stop 110
|-
| valign="top" |Reboot
| valign="top" |pct reboot 110
|-
| valign="top" |Open console
| valign="top" |pct console 110
|-
| valign="top" |Enter shell
| valign="top" |pct enter 110
|-
| valign="top" |Set memory
| valign="top" |pct set 110 --memory 4096
|-
| valign="top" |Set CPU cores
| valign="top" |pct set 110 --cores 4
|-
| valign="top" |Enable startup
| valign="top" |pct set 110 --onboot 1
|-
| valign="top" |Create snapshot
| valign="top" |pct snapshot 110 snapshot-name
|-
| valign="top" |List snapshots
| valign="top" |pct listsnapshot 110
|-
| valign="top" |Roll back snapshot
| valign="top" |pct rollback 110 snapshot-name
|-
| valign="top" |Delete snapshot
| valign="top" |pct delsnapshot 110 snapshot-name
|-
| valign="top" |Create backup
| valign="top" |vzdump 110 --storage backup-storage
|-
| valign="top" |Display help
| valign="top" |pct help
|-
| valign="top" |Display command help
| valign="top" |pct help create
|}

== 30. Final Deployment Checklist ==
• [ ] The workload is appropriate for LXC.

• [ ] An unprivileged container was used unless privilege is required.

• [ ] CPU and memory limits are reasonable.

• [ ] The root disk has adequate free space.

• [ ] Application data is stored appropriately.

• [ ] The IP address and hostname are documented.

• [ ] DNS resolution works.

• [ ] The operating system is updated.

• [ ] SSH keys are configured.

• [ ] Unnecessary services are disabled.

• [ ] Firewall rules are enabled and tested.

• [ ] Automatic startup is configured.

• [ ] Startup order is configured when dependencies exist.

• [ ] Monitoring is active.

• [ ] Scheduled backups are active.

• [ ] A restore has been tested.

• [ ] Temporary snapshots have been removed.

• [ ] The application owner and recovery procedure are documented.

== Conclusion ==
Proxmox LXC containers provide an efficient way to run Linux server workloads with less overhead than complete virtual machines. Their efficiency comes from sharing the Proxmox host’s Linux kernel.

A well-managed deployment begins by selecting the correct virtualization model. Use an unprivileged LXC container for ordinary trusted Linux services, a KVM virtual machine for stronger isolation or specialized operating-system requirements, and a dedicated Linux VM for most production Docker environments.

Reliable container operations depend on more than creating the container. Administrators must also plan storage, networking, security, updates, monitoring, backups, and tested recovery procedures.

== Reference ==
Proxmox VE documentation: <nowiki>https://pve.proxmox.com/pve-docs/</nowiki>

Proxmox containers - Revision history