mirror of
https://github.com/vagrant-libvirt/vagrant-libvirt.git
synced 2025-02-25 18:55:27 -06:00
32 lines
18 KiB
HTML
32 lines
18 KiB
HTML
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>Boxes - Vagrant Libvirt Documentation</title> <link rel="shortcut icon" href="/vagrant-libvirt/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/vagrant-libvirt/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/vagrant-libvirt/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/vagrant-libvirt/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.8.0 --> <title>Boxes | Vagrant Libvirt Documentation</title> <meta name="generator" content="Jekyll v3.9.2" /> <meta property="og:title" content="Boxes" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Create and manage Vagrant machines using Libvirt/QEMU" /> <meta property="og:description" content="Create and manage Vagrant machines using Libvirt/QEMU" /> <link rel="canonical" href="https://vagrant-libvirt.github.io/vagrant-libvirt/boxes.html" /> <meta property="og:url" content="https://vagrant-libvirt.github.io/vagrant-libvirt/boxes.html" /> <meta property="og:site_name" content="Vagrant Libvirt Documentation" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="Boxes" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"Create and manage Vagrant machines using Libvirt/QEMU","headline":"Boxes","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://vagrant-libvirt.github.io/vagrant-libvirt/assets/images/logo.png"}},"url":"https://vagrant-libvirt.github.io/vagrant-libvirt/boxes.html"}</script> <!-- End Jekyll SEO tag --> <script src="https://cdnjs.cloudflare.com/ajax/libs/axios/0.27.2/axios.min.js"></script> <link rel="stylesheet" href="/vagrant-libvirt/assets/css/just-the-docs-light.css" media="(prefers-color-scheme: light)"> <link rel="stylesheet" href="/vagrant-libvirt/assets/css/just-the-docs-dark.css" media="(prefers-color-scheme: dark)"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://vagrant-libvirt.github.io/vagrant-libvirt/" class="site-title lh-tight"> <div class="site-logo"></div> Vagrant Libvirt Documentation </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/" class="nav-list-link">Quickstart</a> </li><li class="nav-list-item"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/installation.html" class="nav-list-link">Installation</a> </li><li class="nav-list-item"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/configuration.html" class="nav-list-link">Configuration</a> </li><li class="nav-list-item active"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/boxes.html" class="nav-list-link active">Boxes</a> <ul id="toc" class="section-nav"> <li class="toc-entry toc-h2"><a href="#existing-boxes">Existing Boxes</a></li> <li class="toc-entry toc-h2"><a href="#creating-boxes">Creating Boxes</a> <ul> <li class="toc-entry toc-h3"><a href="#using-vagrant-package">Using Vagrant Package</a></li> <li class="toc-entry toc-h3"><a href="#from-qcow2-image">From qcow2 Image</a></li> <li class="toc-entry toc-h3"><a href="#packer">Packer</a></li> </ul> </li> <li class="toc-entry toc-h2"><a href="#box-formats">Box Formats</a> <ul> <li class="toc-entry toc-h3"><a href="#version-1">Version 1</a></li> <li class="toc-entry toc-h3"><a href="#version-2-experimental">Version 2 (Experimental)</a></li> </ul> </li> </ul> </li><li class="nav-list-item"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/examples.html" class="nav-list-link">Examples</a> </li><li class="nav-list-item"><a href="https://vagrant-libvirt.github.io/vagrant-libvirt/about/" class="nav-list-link">About</a> </li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search Vagrant Libvirt Documentation" aria-label="Search Vagrant Libvirt Documentation" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> <div class="site-footer"> Plugin Version: <select id="docs-version" onChange="changeVersion(this)"> </select> </div> <script src="/vagrant-libvirt/assets/js/version_switcher-eb6848d1460c4f4ce39c5b1e254763becb2c9db97daec5839fe716b912a7f79d.js"></script> </div> <div id="main-content-wrap" class="main-content-wrap"> <div id="main-content" class="main-content" role="main"> <h2 id="existing-boxes"> <a href="#existing-boxes" class="anchor-heading" aria-labelledby="existing-boxes"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Existing Boxes </h2> <p>Libvirt ready boxes can be downloaded at <a href="https://app.vagrantup.com/boxes/search?provider=libvirt">Vagrant Cloud</a>.</p> <h2 id="creating-boxes"> <a href="#creating-boxes" class="anchor-heading" aria-labelledby="creating-boxes"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Creating Boxes </h2> <p>It’s possible to also create custom boxes using existing boxes as the initial starting point.</p> <div class="info"> If creating a box from a modified vagrant-libvirt machine, ensure that you have set the <code class="language-plaintext highlighter-rouge">config.ssh.insert_key = false</code> in the original Vagrantfile as otherwise Vagrant will replace the default connection key-pair that is required on first boot with one specific to the machine and prevent the default key from working on the exported result. <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">Vagrant</span><span class="p">.</span><span class="nf">configure</span><span class="p">(</span><span class="s2">"2"</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">config</span><span class="o">|</span>
|
||
<span class="c1"># this setting is only recommended if planning to export the</span>
|
||
<span class="c1"># resulting machine</span>
|
||
<span class="n">config</span><span class="p">.</span><span class="nf">ssh</span><span class="p">.</span><span class="nf">insert_key</span> <span class="o">=</span> <span class="kp">false</span>
|
||
|
||
<span class="n">config</span><span class="p">.</span><span class="nf">vm</span><span class="p">.</span><span class="nf">define</span> <span class="ss">:test_vm</span> <span class="k">do</span> <span class="o">|</span><span class="n">test_vm</span><span class="o">|</span>
|
||
<span class="n">test_vm</span><span class="p">.</span><span class="nf">vm</span><span class="p">.</span><span class="nf">box</span> <span class="o">=</span> <span class="s2">"fedora/32-cloud-base"</span>
|
||
<span class="k">end</span>
|
||
<span class="k">end</span></code></pre></figure> </div> <h3 id="using-vagrant-package"> <a href="#using-vagrant-package" class="anchor-heading" aria-labelledby="using-vagrant-package"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Using Vagrant Package </h3> <p>vagrant-libvirt has native support for <a href="https://www.vagrantup.com/docs/cli/package.html"><code class="language-plaintext highlighter-rouge">vagrant package</code></a> via libguestfs <a href="http://libguestfs.org/virt-sysprep.1.html">virt-sysprep</a>. virt-sysprep operations can be customized via the <code class="language-plaintext highlighter-rouge">VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS</code> environment variable; see the <a href="http://libguestfs.org/virt-sysprep.1.html#operations">upstream documentation</a> for further details especially on default sysprep operations enabled for your system.</p> <p>Options to the virt-sysprep command call can be passed via <code class="language-plaintext highlighter-rouge">VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS</code> environment variable.</p> <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">export </span><span class="nv">VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS</span><span class="o">=</span><span class="s2">"--delete /etc/hostname"</span>
|
||
<span class="nv">$ </span>vagrant package
|
||
</code></pre></div></div> <p>For example, on Chef <a href="https://github.com/chef/bento">bento</a> VMs that require SSH hostkeys already set (e.g. bento/debian-7) as well as leave existing LVM UUIDs untouched (e.g. bento/ubuntu-18.04), these can be packaged into vagrant-libvirt boxes like so:</p> <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">export </span><span class="nv">VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS</span><span class="o">=</span><span class="s2">"defaults,-ssh-userdir,-ssh-hostkeys,-lvm-uuids"</span>
|
||
<span class="nv">$ </span>vagrant package
|
||
</code></pre></div></div> <h3 id="from-qcow2-image"> <a href="#from-qcow2-image" class="anchor-heading" aria-labelledby="from-qcow2-image"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> From qcow2 Image </h3> <p>To create a vagrant-libvirt box from a qcow2 image, run <code class="language-plaintext highlighter-rouge">create_box.sh</code> (located in the tools directory):</p> <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>create_box.sh ubuntu14.qcow2
|
||
</code></pre></div></div> <h3 id="packer"> <a href="#packer" class="anchor-heading" aria-labelledby="packer"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Packer </h3> <p>You can also create a box by using <a href="https://packer.io">Packer</a>. Packer templates for use with vagrant-libvirt are available at https://github.com/jakobadam/packer-qemu-templates. After cloning that project you can build a vagrant-libvirt box by running:</p> <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cd </span>packer-qemu-templates
|
||
<span class="nv">$ </span>packer build ubuntu-14.04-server-amd64-vagrant.json
|
||
</code></pre></div></div> <h2 id="box-formats"> <a href="#box-formats" class="anchor-heading" aria-labelledby="box-formats"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Box Formats </h2> <h3 id="version-1"> <a href="#version-1" class="anchor-heading" aria-labelledby="version-1"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Version 1 </h3> <p>This is the original format that most boxes currently use.</p> <p>You can view an example box in the <a href="https://github.com/vagrant-libvirt/vagrant-libvirt/tree/main/example_box"><code class="language-plaintext highlighter-rouge">example_box/directory</code></a>. That directory also contains instructions on how to build a box.</p> <p>The box is a tarball containing:</p> <ul> <li>qcow2 image file named <code class="language-plaintext highlighter-rouge">box.img</code></li> <li><code class="language-plaintext highlighter-rouge">metadata.json</code> file describing box image (<code class="language-plaintext highlighter-rouge">provider</code>, <code class="language-plaintext highlighter-rouge">virtual_size</code>, <code class="language-plaintext highlighter-rouge">format</code>)</li> <li><code class="language-plaintext highlighter-rouge">Vagrantfile</code> that does default settings for the provider-specific configuration for this provider</li> </ul> <h3 id="version-2-experimental"> <a href="#version-2-experimental" class="anchor-heading" aria-labelledby="version-2-experimental"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Version 2 (Experimental) </h3> <p>Due to the limitation of only being able to handle a single disk with the version 1 format, a new format was added to support boxes that need to specify multiple disks. This is still currently experimental and as such is not the default format. Packaging support is in place and will automatically alert you if attempting to package a machine with additional disks attached. To enable the new format to verify ahead of it becoming the default, export the variable <code class="language-plaintext highlighter-rouge">VAGRANT_LIBVIRT_BOX_FORMAT_VERSION=v2</code> before running <code class="language-plaintext highlighter-rouge">vagrant package</code></p> <p>Additionally there is a script in the tools folder (<a href="https://github.com/vagrant-libvirt/vagrant-libvirt/blob/main/tools/create_box_with_two_disks.sh"><code class="language-plaintext highlighter-rouge">tools/create_box_with_two_disks.sh</code></a>) that provides a guideline on how to create such a box from qcow2 images should it not be practical use a vagrant machine with additional storage as a starting point.</p> <p>At it’s most basic, it expects an array of disks to allow a specific order to be presented. Disks will be attached in this order and as such assume device names base on this within the VM. The ‘path’ attribute is required, and is expected to be relative to the base of the box. This should allow placing the disk images within a nested directory within the box if it useful for those with a larger number of disks. The name allows overriding the target volume name that will be used in the libvirt storage pool. Note that vagrant-libvirt will still prefix the volume name with <code class="language-plaintext highlighter-rouge">#{box_name}_vagrant_box_image_#{box_version}_</code> to avoid accidental clashes with other boxes.</p> <p>Format and virtual size need no longer be specified as they are now retrieved directly from the provided image using <code class="language-plaintext highlighter-rouge">qemu-img info ...</code>.</p> <p>Example format:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
|
||
</span><span class="nl">"disks"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
|
||
</span><span class="p">{</span><span class="w">
|
||
</span><span class="nl">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"disk1.img"</span><span class="w">
|
||
</span><span class="p">},</span><span class="w">
|
||
</span><span class="p">{</span><span class="w">
|
||
</span><span class="nl">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"disk2.img"</span><span class="p">,</span><span class="w">
|
||
</span><span class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"secondary_disk"</span><span class="w">
|
||
</span><span class="p">},</span><span class="w">
|
||
</span><span class="p">{</span><span class="w">
|
||
</span><span class="nl">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"disk3.img"</span><span class="w">
|
||
</span><span class="p">}</span><span class="w">
|
||
</span><span class="p">],</span><span class="w">
|
||
</span><span class="nl">"provider"</span><span class="p">:</span><span class="w"> </span><span class="s2">"libvirt"</span><span class="w">
|
||
</span><span class="p">}</span><span class="w">
|
||
</span></code></pre></div></div> <hr> <footer> <div class="d-flex mt-2"> <p class="text-small text-grey-dk-000 mb-0"> <a href="https://github.com/vagrant-libvirt/vagrant-libvirt/tree/main/boxes.markdown" id="edit-this-page">Edit this page on GitHub</a> </p> </div> </footer> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
|