Puppet Learning VM Setup Guide: Import, Networking, SSH Access, and Troubleshooting

The Puppet Learning VM is a prebuilt lab image for learning Puppet Enterprise workflows without building a full environment from scratch. This walkthrough is for DevOps engineers and learners who need a reliable setup path, including import, networking, SSH access, and practical troubleshooting.

Originally published on 2016-07-09; fully revised and updated.

Download and host requirements

Download the Learning VM archive from the original source: https://pe-education-vms.s3.amazonaws.com/learning/learning_puppet_vm.zip.

• Internet-enabled Windows, OS X/macOS, or Linux host.
• At least 10GB free disk space.
• CPU virtualization support enabled (VT-x or AMD-V).
• Up-to-date desktop virtualization software.

Virtualization platform options

The original setup guidance recommends either VirtualBox or VMware desktop products.

Setup workflow overview

flowchart TD
    A[Download VM zip] --> B[Verify checksum]
    B --> C[Install virtualization tool]
    C --> D[Import OVA appliance]
    D --> E[Set memory and network]
    E --> F[Boot VM]
    F --> G[Read splash IP and password]
    G --> H[SSH login as root]
    G --> I[Open Quest Guide over HTTP]
    G --> J[Open PE Console over HTTPS]

Step-by-step setup

1) Verify download integrity (optional but recommended)

The original instructions reference an MD5 file alongside the ZIP. On Unix-like systems, compare your local checksum output with learning_puppet_vm.zip.md5. On Windows, the original guide suggests Microsoft File Checksum Integrity Verifier: FCIV.

md5 learning_puppet_vm.zip
cat learning_puppet_vm.zip.md5Code language: CSS (css)

2) Import the OVA (do not open it directly)

The Learning VM uses OVA format and should be imported as an appliance. In your virtualization app, use File and then Import or Import Appliance.

3) Tune VM settings before first boot

Before starting the VM, allocate resources and choose networking.

• Recommended memory: 4GB for best performance.
• If host memory is limited, 3GB or 2GB may run but can be less stable.
• Preferred network mode: Bridged with autodetect/default adapter name.

4) Boot and connect over SSH

After boot, note the splash-screen IP and generated root password. The original guidance recommends SSH instead of interactive console login. Windows users can use PuTTY.

ssh root@<IPADDRESS>
ntpdate pool.ntp.orgCode language: HTML, XML (xml)

It can take several minutes after boot for Puppet Enterprise services to become fully available.

5) Open the Quest Guide and PE console

• Quest Guide: http://<VM_IP_ADDRESS> (HTTP)
• PE Console: https://<VM_IP_ADDRESS> (HTTPS)
• The original quest content mentions PE credentials admin/puppetlabs inside the guide.

Fallback networking: NAT with port forwarding

If the VM IP is unreachable, switch the adapter to NAT and configure port forwarding as documented in the source material.

ssh -p 2222 root@localhost
# Quest Guide
http://localhost:8080
# PE Console
https://localhost:8443Code language: CSS (css)

Troubleshooting reference

For updated troubleshooting text, see the upstream repository: courseware-lvm SETUP.md. For unresolved issues, the original contact is learningvm@puppetlabs.com. General PE issues were linked to Puppet Enterprise Known Issues.

Puppet services fail or PE console is unavailable

Wait a few minutes after boot, then check service status. If services are stopped, verify memory allocation before restarting them.

systemctl --all | grep pe-
service pe-puppetdb start

Cannot find the VM password

The password is shown on the VM splash screen at boot. If logged in locally, print it from:

cat /var/local/passwordCode language: JavaScript (javascript)

Quest task not marked complete

The quest tool uses Serverspec checks, and some tasks depend on shell history. Re-login can reinitialize /root/.bash_history. You can inspect quest specs in ~/.testing/spec/localhost/ if a matcher appears too restrictive.

Cowsay package issue (Learning VM 2.29 note)

The original troubleshooting notes a quest error where provider => 'gem' should be used instead of ensure => 'gem'. If needed, install the cached gem manually.

gem install /var/cache/rubygems/gems/cowsay-0.2.0.gemCode language: JavaScript (javascript)

No IP address or unreachable VM

If your host network changed, the splash IP may be stale. Check the current address from the VM console:

facter ipaddress

Terminal scrollback is blocked

The VM uses tmux. Enter scroll mode with Ctrl-b, then [. Use arrow keys to scroll and press q to exit.

VirtualBox “Rejecting I/O input from offline devices”

The original fix is to reduce the VM to 1 processor and disable I/O APIC under system settings.

Best practices and common pitfalls

• Import the OVA as an appliance; opening the file directly often fails.
• Set memory before first boot to avoid unstable PE services.
• Use bridged networking first, then NAT with port forwarding if needed.
• Use SSH for day-to-day work instead of relying on the VM console.
• Use http for Quest Guide and https for PE Console to avoid endpoint confusion.
• If behavior differs from this guide, check the upstream troubleshooting file because Learning VM content has changed over time.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.