{"id":480,"date":"2026-10-14T17:01:48","date_gmt":"2026-10-14T17:01:48","guid":{"rendered":"http:\/\/www.scmgalaxy.com\/tutorials\/2016\/07\/09\/setup-a-puppet-learning-vm\/"},"modified":"2026-10-14T17:01:48","modified_gmt":"2026-10-14T17:01:48","slug":"setup-a-puppet-learning-vm","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/setup-a-puppet-learning-vm\/","title":{"rendered":"Puppet Learning VM Setup Guide: Import, Networking, SSH Access, and Troubleshooting"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><em>Originally published on 2016-07-09; fully revised and updated.<\/em><\/p>\n\n\n<div class=\"wp-block-image\">\n<figure class=\"aligncenter size-full\"><img decoding=\"async\" src=\"https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2016\/07\/setup-a-puppet-learning-vm-1.png\" alt=\"Puppet Learning VM setup\"\/><\/figure>\n<\/div>\n\n\n<h2 class=\"wp-block-heading\">Download and host requirements<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Download the Learning VM archive from the original source: <a href=\"https:\/\/pe-education-vms.s3.amazonaws.com\/learning\/learning_puppet_vm.zip\">https:\/\/pe-education-vms.s3.amazonaws.com\/learning\/learning_puppet_vm.zip<\/a>.<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>Internet-enabled Windows, OS X\/macOS, or Linux host.<\/li><li>At least 10GB free disk space.<\/li><li>CPU virtualization support enabled (VT-x or AMD-V).<\/li><li>Up-to-date desktop virtualization software.<\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Virtualization platform options<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The original setup guidance recommends either VirtualBox or VMware desktop products.<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Tool<\/th><th>Platform in original guidance<\/th><th>Cost model<\/th><th>Download<\/th><\/tr><\/thead><tbody><tr><td>VirtualBox<\/td><td>Linux, OS X, Windows<\/td><td>Free<\/td><td><a href=\"https:\/\/www.virtualbox.org\/wiki\/Downloads\">virtualbox.org<\/a><\/td><\/tr><tr><td>VMware Fusion<\/td><td>Mac<\/td><td>Commercial<\/td><td><a href=\"https:\/\/www.vmware.com\/products\/fusion\/\">vmware.com\/products\/fusion<\/a><\/td><\/tr><tr><td>VMware Workstation<\/td><td>Windows<\/td><td>Commercial<\/td><td><a href=\"https:\/\/www.vmware.com\/products\/workstation\/\">vmware.com\/products\/workstation<\/a><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\">Setup workflow overview<\/h2>\n\n\n\n<pre class=\"mermaid\">\nflowchart TD\n    A[Download VM zip] --> B[Verify checksum]\n    B --> C[Install virtualization tool]\n    C --> D[Import OVA appliance]\n    D --> E[Set memory and network]\n    E --> F[Boot VM]\n    F --> G[Read splash IP and password]\n    G --> H[SSH login as root]\n    G --> I[Open Quest Guide over HTTP]\n    G --> J[Open PE Console over HTTPS]\n<\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Step-by-step setup<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1) Verify download integrity (optional but recommended)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The original instructions reference an MD5 file alongside the ZIP. On Unix-like systems, compare your local checksum output with <code>learning_puppet_vm.zip.md5<\/code>. On Windows, the original guide suggests Microsoft File Checksum Integrity Verifier: <a href=\"https:\/\/www.microsoft.com\/en-us\/download\/details.aspx?id=11533\">FCIV<\/a>.<\/p>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-1\" data-shcb-language-name=\"CSS\" data-shcb-language-slug=\"css\"><span><code class=\"hljs language-css language-bash\"><span class=\"hljs-selector-tag\">md5<\/span> <span class=\"hljs-selector-tag\">learning_puppet_vm<\/span><span class=\"hljs-selector-class\">.zip<\/span>\n<span class=\"hljs-selector-tag\">cat<\/span> <span class=\"hljs-selector-tag\">learning_puppet_vm<\/span><span class=\"hljs-selector-class\">.zip<\/span><span class=\"hljs-selector-class\">.md5<\/span><\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-1\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">CSS<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">css<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h3 class=\"wp-block-heading\">2) Import the OVA (do not open it directly)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The Learning VM uses OVA format and should be imported as an appliance. In your virtualization app, use <strong>File<\/strong> and then <strong>Import<\/strong> or <strong>Import Appliance<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">3) Tune VM settings before first boot<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Before starting the VM, allocate resources and choose networking.<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>Recommended memory: <strong>4GB<\/strong> for best performance.<\/li><li>If host memory is limited, 3GB or 2GB may run but can be less stable.<\/li><li>Preferred network mode: <strong>Bridged<\/strong> with autodetect\/default adapter name.<\/li><\/ul>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Network mode<\/th><th>When to use<\/th><th>How you access the VM<\/th><th>Trade-off<\/th><\/tr><\/thead><tbody><tr><td>Bridged<\/td><td>Default recommendation<\/td><td>Directly via VM IP address on your LAN<\/td><td>Can be blocked by some local network policies<\/td><\/tr><tr><td>NAT with port forwarding<\/td><td>Fallback when bridged networking fails<\/td><td>Via localhost mapped ports<\/td><td>Requires manual port mapping<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">4) Boot and connect over SSH<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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 <a href=\"http:\/\/www.putty.org\/\">PuTTY<\/a>.<\/p>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-2\" data-shcb-language-name=\"HTML, XML\" data-shcb-language-slug=\"xml\"><span><code class=\"hljs language-xml language-bash\">ssh root@<span class=\"hljs-tag\">&lt;<span class=\"hljs-name\">IPADDRESS<\/span>&gt;<\/span>\nntpdate pool.ntp.org<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-2\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">HTML, XML<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">xml<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<p class=\"wp-block-paragraph\">It can take several minutes after boot for Puppet Enterprise services to become fully available.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">5) Open the Quest Guide and PE console<\/h3>\n\n\n\n<ul class=\"wp-block-list\"><li>Quest Guide: <code>http:\/\/&lt;VM_IP_ADDRESS&gt;<\/code> (HTTP)<\/li><li>PE Console: <code>https:\/\/&lt;VM_IP_ADDRESS&gt;<\/code> (HTTPS)<\/li><li>The original quest content mentions PE credentials <code>admin\/puppetlabs<\/code> inside the guide.<\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Fallback networking: NAT with port forwarding<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">If the VM IP is unreachable, switch the adapter to NAT and configure port forwarding as documented in the source material.<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Name<\/th><th>Protocol<\/th><th>Host IP<\/th><th>Host Port<\/th><th>Guest Port<\/th><\/tr><\/thead><tbody><tr><td>SSH<\/td><td>TCP<\/td><td>127.0.0.1<\/td><td>2222<\/td><td>22<\/td><\/tr><tr><td>HTTP<\/td><td>TCP<\/td><td>127.0.0.1<\/td><td>8080<\/td><td>80<\/td><\/tr><tr><td>HTTPS<\/td><td>TCP<\/td><td>127.0.0.1<\/td><td>8443<\/td><td>443<\/td><\/tr><tr><td>GRAPHITE<\/td><td>TCP<\/td><td>127.0.0.1<\/td><td>8090<\/td><td>90<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-3\" data-shcb-language-name=\"CSS\" data-shcb-language-slug=\"css\"><span><code class=\"hljs language-css language-bash\"><span class=\"hljs-selector-tag\">ssh<\/span> <span class=\"hljs-selector-tag\">-p<\/span> 2222 <span class=\"hljs-selector-tag\">root<\/span><span class=\"hljs-keyword\">@localhost<\/span>\n# Quest Guide\n<span class=\"hljs-attribute\">http:<\/span>\/\/<span class=\"hljs-attribute\">localhost:<\/span><span class=\"hljs-number\">8080<\/span>\n# PE Console\n<span class=\"hljs-attribute\">https:<\/span>\/\/<span class=\"hljs-attribute\">localhost:<\/span><span class=\"hljs-number\">8443<\/span><\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-3\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">CSS<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">css<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h2 class=\"wp-block-heading\">Troubleshooting reference<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">For updated troubleshooting text, see the upstream repository: <a href=\"https:\/\/github.com\/puppetlabs\/courseware-lvm\/blob\/master\/SETUP.md#troubleshooting\">courseware-lvm SETUP.md<\/a>. For unresolved issues, the original contact is <a href=\"mailto:learningvm@puppetlabs.com\">learningvm@puppetlabs.com<\/a>. General PE issues were linked to <a href=\"https:\/\/docs.puppetlabs.com\/pe\/latest\/release_notes_known_issues.html\">Puppet Enterprise Known Issues<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Puppet services fail or PE console is unavailable<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Wait a few minutes after boot, then check service status. If services are stopped, verify memory allocation before restarting them.<\/p>\n\n\n<pre class=\"wp-block-code\"><span><code class=\"hljs language-bash\">systemctl --all | grep pe-\nservice pe-puppetdb start<\/code><\/span><\/pre>\n\n\n<h3 class=\"wp-block-heading\">Cannot find the VM password<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The password is shown on the VM splash screen at boot. If logged in locally, print it from:<\/p>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-4\" data-shcb-language-name=\"JavaScript\" data-shcb-language-slug=\"javascript\"><span><code class=\"hljs language-javascript language-bash\">cat \/<span class=\"hljs-keyword\">var<\/span>\/local\/password<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-4\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">JavaScript<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">javascript<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h3 class=\"wp-block-heading\">Quest task not marked complete<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The quest tool uses <a href=\"http:\/\/serverspec.org\/\">Serverspec<\/a> checks, and some tasks depend on shell history. Re-login can reinitialize <code>\/root\/.bash_history<\/code>. You can inspect quest specs in <code>~\/.testing\/spec\/localhost\/<\/code> if a matcher appears too restrictive.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Cowsay package issue (Learning VM 2.29 note)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The original troubleshooting notes a quest error where <code>provider =&gt; 'gem'<\/code> should be used instead of <code>ensure =&gt; 'gem'<\/code>. If needed, install the cached gem manually.<\/p>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-5\" data-shcb-language-name=\"JavaScript\" data-shcb-language-slug=\"javascript\"><span><code class=\"hljs language-javascript language-bash\">gem install \/<span class=\"hljs-keyword\">var<\/span>\/cache\/rubygems\/gems\/cowsay<span class=\"hljs-number\">-0.2<\/span><span class=\"hljs-number\">.0<\/span>.gem<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-5\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">JavaScript<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">javascript<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h3 class=\"wp-block-heading\">No IP address or unreachable VM<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">If your host network changed, the splash IP may be stale. Check the current address from the VM console:<\/p>\n\n\n<pre class=\"wp-block-code\"><span><code class=\"hljs language-bash\">facter ipaddress<\/code><\/span><\/pre>\n\n\n<h3 class=\"wp-block-heading\">Terminal scrollback is blocked<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The VM uses tmux. Enter scroll mode with <code>Ctrl-b<\/code>, then <code>[<\/code>. Use arrow keys to scroll and press <code>q<\/code> to exit.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">VirtualBox &#8220;Rejecting I\/O input from offline devices&#8221;<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The original fix is to reduce the VM to 1 processor and disable <code>I\/O APIC<\/code> under system settings.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Best practices and common pitfalls<\/h2>\n\n\n\n<ul class=\"wp-block-list\"><li>Import the OVA as an appliance; opening the file directly often fails.<\/li><li>Set memory before first boot to avoid unstable PE services.<\/li><li>Use bridged networking first, then NAT with port forwarding if needed.<\/li><li>Use SSH for day-to-day work instead of relying on the VM console.<\/li><li>Use <code>http<\/code> for Quest Guide and <code>https<\/code> for PE Console to avoid endpoint confusion.<\/li><li>If behavior differs from this guide, check the upstream troubleshooting file because Learning VM content has changed over time.<\/li><\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Learn how to set up the Puppet Learning VM from the OVA download through first login, networking, and web access. This revised guide also consolidates the most useful troubleshooting fixes from the original courseware.<\/p>\n","protected":false},"author":1,"featured_media":2889,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[89],"tags":[1122,545,1179,664,661,593,159,663,230,968,662],"class_list":["post-480","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-puppet","tag-guide","tag-how","tag-how-to-setup-puppet-learning-vm","tag-learn-puppet","tag-learning-vm","tag-process","tag-puppet","tag-puppet-tutorial","tag-setup","tag-virtual-machine","tag-vm"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/480","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=480"}],"version-history":[{"count":5,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/480\/revisions"}],"predecessor-version":[{"id":79363,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/480\/revisions\/79363"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media\/2889"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=480"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=480"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=480"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}