basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    The first LXC container in Proxmox: Debian from a template, network, SSH by key and a directory shared with the host

    A Debian 13 container from a Proxmox template is a small server that starts in a couple of seconds and takes tens of megabytes of memory when idle. Download the template, create an unprivileged container with an address on the home network and an SSH key, mount a host directory into it and install nginx to check. Don’t use such a container for Docker — that’s what a VM is for.

    What you’ll end up with

    template    debian-13-standard_13.6-1 from the Proxmox template repository
    container   201, files1: unprivileged, 1 core, 512 MB of memory, 8 GB disk
    network     10.0.0.21 on the home network through vmbr0, root logs in by key
    directory   the host's /srv/share is visible in the container as /srv/share
    check       nginx answers at http://10.0.0.21

    Commands run in the node’s Shell as root. In the UI the Create CT wizard does the same; the wizard fields match the pct create options, so they’re shown side by side below. Network and addresses are as in Installing Proxmox: router 10.0.0.1, host 10.0.0.2. The public key for login is in /root/example-user.pub — as in VM template with cloud-init.

    Steps

    1. Download the Debian template

      pveam update                                   # fresh template list
      pveam available --section system | grep debian
      # system          debian-12-standard_12.12-1_amd64.tar.zst
      # system          debian-13-standard_13.6-1_amd64.tar.zst
      pveam download local debian-13-standard_13.6-1_amd64.tar.zst
      pveam list local                               # local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst

      In the UI: local › CT Templates › Templates. A template is an archive of a ready system, about 120 MB. The same list has Ubuntu 24.04 and 26.04, Alpine, Rocky, Fedora and ready-made TurnKey applications.

    2. Create the container

      pct create 201 local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst \
        --hostname files1 --unprivileged 1 --features nesting=1 \
        --cores 1 --memory 512 --swap 512 \
        --rootfs local-lvm:8 \
        --net0 name=eth0,bridge=vmbr0,ip=10.0.0.21/24,gw=10.0.0.1 \
        --nameserver 10.0.0.1 \
        --ssh-public-keys /root/example-user.pub \
        --onboot 1 --start 1
      Option Wizard field What it means
      --unprivileged 1 Unprivileged container uids inside are shifted by 100000: the container’s root is nobody on the host (VM or LXC)
      --features nesting=1 Nesting a recent systemd in the guest needs access to /proc and /sys, which this option gives; the wizard turns it on itself
      --memory 512 --swap 512 Memory, Swap a cgroups limit, not allocated memory: in use is only what the system inside eats
      --rootfs local-lvm:8 Disks an 8 GB root volume on the thin pool; on ZFS — local-zfs:8
      --net0 … Network eth0 on the vmbr0 bridge, its own address; ip=dhcp — an address from the router
      --ssh-public-keys SSH public key(s) the key goes into the container’s /root/.ssh/authorized_keys
      --onboot 1 Start at boot start after the host reboots

      No root password is set: you log in inside with the key, and from the host with pct enter. The container starts in a couple of seconds.

    3. Log in and update

      ssh [email protected]                  # from a computer, by key
      # or from the host, with no network or password:
      pct enter 201

      Inside it’s regular Debian:

      apt update && apt full-upgrade -y
      uname -r                            # 7.0.14-25-pve — the host kernel, no kernel of its own
      free -m                             # total 512: the cgroups limit shows up as all the memory

      A user of your own and login without root — as on any server (First login to a server). The kernel, modules and kernel-level sysctl aren’t configured in a container: that’s done on the host and applies to everyone.

    4. Mount a host directory

      Data needed by both the host and the container — say, a shared folder — lives in a host directory mounted into the container. First give the directory to the container’s root: on the host that’s uid 100000.

      mkdir -p /srv/share
      chown 100000:100000 /srv/share
      pct set 201 -mp0 /srv/share,mp=/srv/share
      pct reboot 201
      • mp0 is the first mount point; the next ones are mp1, mp2.
      • The host path has no symbolic links: Proxmox doesn’t accept them.
      • Only root@pam can mount a host directory, and only by command: the mount point wizard in the UI creates volumes on storages and doesn’t offer host directories.
      • If a user with uid 1000 will write in the container, on the host that’s 101000:101000.

      Such a directory doesn’t go into the container backup: vzdump copies only Proxmox volumes. Back up the host directory separately, from the host.

    5. Install nginx to check

      pct exec 201 -- apt install -y nginx
      pct exec 201 -- sh -c 'echo "files1 is up" > /var/www/html/index.html'

      pct exec runs a command in the container right from the host, without SSH or a password — that’s how containers are set up by script. Open http://10.0.0.21 from a computer — a page with the text files1 is up.

    6. Take a snapshot

      pct snapshot 201 clean --description "Debian 13 after setup"
      pct listsnapshot 201

      Before an experiment with the container, the rollback is pct rollback 201 clean. The snapshot lives where the container’s disk is and doesn’t count as a backup (A snapshot isn’t a backup); nightly copies — Backups in Proxmox.

    If it doesn’t work

    pveam download — 400 Parameter verification failed, or the template isn’t there

    Cause
    The host’s template list is old, and the template name has a version in it: 13.6-1 was replaced by a newer one.
    Fix
    pveam update, then pveam available --section system | grep debian — take the full name from there.

    ssh [email protected] with a password — Permission denied

    Cause
    On Debian root logs in over SSH by key only: PermitRootLogin prohibit-password by default.
    Fix
    Log in with the key from --ssh-public-keys, or from the host with pct enter 201 — no password and no network.

    After login: perl: warning: Setting locale failed or setlocale: LC_ALL: cannot change locale

    Cause
    SSH passes on your computer’s locale (say, de_DE.UTF-8), and the minimal template doesn’t have it generated.
    Fix
    In the container: dpkg-reconfigure locales and tick your locale; or remove SendEnv LANG LC_* from ssh_config on your computer.

    In the mounted directory files belong to nobody, and writes fail with Permission denied

    Cause
    The container is unprivileged: root inside is uid 100000 on the host, user 1000 is uid 101000. The host directory belongs to the host’s root, which is foreign to the container.
    Fix
    On the host: chown -R 100000:100000 /srv/share for the container’s root or 101000:101000 for its user 1000.

    The container backup doesn’t include the files from /srv/share

    Cause
    Host directories mounted into the container (bind mounts) don’t go into the container backup: vzdump copies only Proxmox volumes.
    Fix
    Back up the host directory separately — Kopia or rsync from the host (A backup that outlives the server). Or keep the data on a Proxmox volume: pct set 201 -mp0 local-lvm:50,mp=/srv/share — such a volume goes into the backup.

    apt update in the container: Temporary failure resolving 'deb.debian.org'

    Cause
    The container has no working DNS: without --nameserver it takes the host’s DNS, and that isn’t reachable from the container’s network.
    Fix
    pct set 201 --nameserver 10.0.0.1 and pct reboot 201. Check with cat /etc/resolv.conf inside.

    How to check

    From the host:

    pct list                            # 201  running  files1
    pct config 201                      # unprivileged: 1, features: nesting=1, mp0: /srv/share,mp=/srv/share
    pct exec 201 -- touch /srv/share/test-from-ct
    ls -ln /srv/share                   # the file owner is 100000: the container's root is shifted on the host

    From a computer: ssh [email protected] hostname prints files1, curl http://10.0.0.21 returns the page. After pct reboot 201 the container answers again within a couple of seconds.