cdist-web/src/extra/manual/beta/cdist-preos.html

402 lines
20 KiB
HTML

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>22. PreOS &mdash; cdist 6.9.1 documentation</title>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="23. cdist integration / using cdist as library" href="cdist-integration.html" />
<link rel="prev" title="21. Trigger" href="cdist-trigger.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> cdist
<img src="_static/cdist-logo.jpeg" class="logo" alt="Logo"/>
</a>
<div class="version">
6.9.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="cdist-why.html">1. Why should I use cdist?</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-features.html">2. Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-os.html">3. Supported operating systems</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-install.html">4. How to install cdist</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-upgrade.html">5. How to upgrade cdist</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-support.html">6. Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-quickstart.html">7. Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-real-world.html">8. Dive into real world cdist</a></li>
<li class="toctree-l1"><a class="reference internal" href="man1/cdist.html">9. cdist(1)</a></li>
<li class="toctree-l1"><a class="reference internal" href="man1/cdist-dump.html">10. cdist-dump(1)</a></li>
<li class="toctree-l1"><a class="reference internal" href="man1/cdist-new-type.html">11. cdist-new-type(1)</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-bootstrap.html">12. Bootstrap</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-configuration.html">13. Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-manifest.html">14. Manifest</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-type.html">15. cdist type</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-types.html">16. cdist types</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-explorer.html">17. Explorer</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-messaging.html">18. Messaging</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-parallelization.html">19. Parallelization</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-inventory.html">20. Inventory</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-trigger.html">21. Trigger</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">22. PreOS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#description">22.1. Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="#preos-creation">22.2. PreOS creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#implementing-new-preos-sub-command">22.3. Implementing new PreOS sub-command</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#example-of-writing-new-dummy-preos-sub-command">22.3.1. Example of writing new dummy preos sub-command</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#module-based-preos">22.3.1.1. Module-based preos:</a></li>
<li class="toctree-l4"><a class="reference internal" href="#class-based-preos">22.3.1.2. Class based preos:</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#simple-tipical-use-case-for-using-preos-and-trigger">22.4. Simple tipical use case for using PreOS and trigger</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cdist-integration.html">23. cdist integration / using cdist as library</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-reference.html">24. Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-best-practice.html">25. Best practice</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-stages.html">26. Execution stages</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-cache.html">27. Local cache overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-saving-output-streams.html">28. Saving output streams</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-remote-exec-copy.html">29. Remote exec and copy commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-hacker.html">30. Hacking</a></li>
<li class="toctree-l1"><a class="reference internal" href="cdist-troubleshooting.html">31. Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">cdist</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li><span class="section-number">22. </span>PreOS</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/cdist-preos.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="preos">
<h1><span class="section-number">22. </span>PreOS<a class="headerlink" href="#preos" title="Permalink to this headline"></a></h1>
<div class="section" id="description">
<h2><span class="section-number">22.1. </span>Description<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
<p>With cdist you can install and configure new machines. You can use cdist to
create PreOS, minimal OS whose purpose is to boot a new machine.
After PreOS is booted, the machine is ready for installing the desired OS and
afterwards it is ready for configuration.</p>
</div>
<div class="section" id="preos-creation">
<h2><span class="section-number">22.2. </span>PreOS creation<a class="headerlink" href="#preos-creation" title="Permalink to this headline"></a></h2>
<p>With cdist you can create PreOS.
Currently supported PreOS-es include:</p>
<ul class="simple">
<li><p>debian</p></li>
<li><p>ubuntu</p></li>
<li><p>devuan</p></li>
</ul>
<p>PreOS is created using the <code class="docutils literal notranslate"><span class="pre">cdist</span> <span class="pre">preos</span></code> command.
This command has subcommands that determine the desired PreOS.</p>
<p>For example, to create an ubuntu PreOS:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ cdist preos ubuntu /preos/preos-ubuntu -B -C <span class="se">\</span>
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu <span class="se">\</span>
-t <span class="s2">&quot;/usr/bin/curl 192.168.111.5:3000/cdist/install/&quot;</span>
</pre></div>
</div>
<p>For more info about the available options see the cdist manual page.</p>
<p>This will bootstrap (<code class="docutils literal notranslate"><span class="pre">-B</span></code>) ubuntu PreOS in <code class="docutils literal notranslate"><span class="pre">/preos/preos-ubuntu</span></code> directory, it
will be configured (<code class="docutils literal notranslate"><span class="pre">-C</span></code>) using default built-in initial manifest and with
specified ssh authorized key (<code class="docutils literal notranslate"><span class="pre">-k</span></code>) and with specified trigger command (<code class="docutils literal notranslate"><span class="pre">-t</span></code>).
After bootstrapping and configuration PXE
boot directory will be created (<code class="docutils literal notranslate"><span class="pre">-p</span></code>) in <code class="docutils literal notranslate"><span class="pre">/preos/pxe-ubuntu</span></code>.</p>
<p>After PreOS is created, new machines can be booted using the created PXE
(after proper dhcp and tftp settings).</p>
<p>Since PreOS is configured with ssh authorized key it can be accessed through
ssh, i.e. it can be further installed and configured with cdist.</p>
<p>When installing and configuring new machines using cdist's PreOS concept
cdist can use triggering for host installation/configuration, which is described
in the previous chapter.</p>
<p>When new machine is booted with PreOS then trigger command is executed.
Machine will connect to cdist trigger server. If the request is, for example,
for installation then cdist trigger server will start install command for the
client host using parameters specified at trigger server startup.</p>
</div>
<div class="section" id="implementing-new-preos-sub-command">
<h2><span class="section-number">22.3. </span>Implementing new PreOS sub-command<a class="headerlink" href="#implementing-new-preos-sub-command" title="Permalink to this headline"></a></h2>
<p>preos command is implemented as a plugin system. This plugin system scans for
preos subcommands in the <code class="docutils literal notranslate"><span class="pre">cdist/preos/</span></code> distribution directory and also in
<code class="docutils literal notranslate"><span class="pre">~/.cdist/preos/</span></code> directory if it exists.</p>
<p>preos subcommand is a module or a class that satisfies the following:</p>
<ul class="simple">
<li><p>it has the attribute <code class="docutils literal notranslate"><span class="pre">_cdist_preos</span></code> set to <code class="docutils literal notranslate"><span class="pre">True</span></code></p></li>
<li><p>it defines a function/method <code class="docutils literal notranslate"><span class="pre">commandline</span></code>.</p></li>
</ul>
<p>For a module-based preos subcommand, the <code class="docutils literal notranslate"><span class="pre">commandline</span></code> function accepts a
module object as its first argument and the list of command line
arguments (<code class="docutils literal notranslate"><span class="pre">sys.argv[2:]</span></code>).</p>
<p>For a class-based preos subcommand <code class="docutils literal notranslate"><span class="pre">commandline</span></code> method should be
static-method and must accept a class as its first argument and the
list of command line arguments (<code class="docutils literal notranslate"><span class="pre">sys.argv[2:]</span></code>).</p>
<p>If preos scanning finds a module/class that has <code class="docutils literal notranslate"><span class="pre">_cdist_preos</span></code> set
to <code class="docutils literal notranslate"><span class="pre">True</span></code> and a function/method <code class="docutils literal notranslate"><span class="pre">commandline</span></code> then this module/class is
registered to preos subcommands. The name of the command is set to <code class="docutils literal notranslate"><span class="pre">_preos_name</span></code>
attribute if defined in the module/class, defaulting to the module/class name in lowercase.
When a registered preos subcommand is specified, <code class="docutils literal notranslate"><span class="pre">commandline</span></code>
will be called with the first argument set to module/class and the second
argument set to <code class="docutils literal notranslate"><span class="pre">sys.argv[2:]</span></code>.</p>
<div class="section" id="example-of-writing-new-dummy-preos-sub-command">
<h3><span class="section-number">22.3.1. </span>Example of writing new dummy preos sub-command<a class="headerlink" href="#example-of-writing-new-dummy-preos-sub-command" title="Permalink to this headline"></a></h3>
<div class="section" id="module-based-preos">
<h4><span class="section-number">22.3.1.1. </span>Module-based preos:<a class="headerlink" href="#module-based-preos" title="Permalink to this headline"></a></h4>
<ol class="arabic simple">
<li><p>Create directory <code class="docutils literal notranslate"><span class="pre">~/.cdist/preos/</span></code> if it does not exist</p></li>
<li><p>Create <code class="docutils literal notranslate"><span class="pre">~/.cdist/preos/netbsd.py</span></code> with the following contents:</p></li>
</ol>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">_preos_name</span> <span class="o">=</span> <span class="s1">&#39;netbsd&#39;</span>
<span class="n">_cdist_preos</span> <span class="o">=</span> <span class="kc">True</span>
<span class="k">def</span> <span class="nf">commandline</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;NetBSD PreOS: </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">args</span><span class="p">))</span>
</pre></div>
</div>
<p>When you try to run this new preos you will get:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ cdist preos -L
Available PreOS-es:
- debian
- devuan
- netbsd
- ubuntu
$ cdist preos netbsd
NetBSD PreOS: <span class="o">[]</span>
</pre></div>
</div>
</div>
<div class="section" id="class-based-preos">
<h4><span class="section-number">22.3.1.2. </span>Class based preos:<a class="headerlink" href="#class-based-preos" title="Permalink to this headline"></a></h4>
<ol class="arabic simple">
<li><p>Create directory <code class="docutils literal notranslate"><span class="pre">~/.cdist/preos/</span></code> if it does not exist</p></li>
<li><p>Create <code class="docutils literal notranslate"><span class="pre">~/.cdist/preos/freebsd.py</span></code> with the following contents:</p></li>
</ol>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FreeBSD</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="n">_cdist_preos</span> <span class="o">=</span> <span class="kc">True</span>
<span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">commandline</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;FreeBSD dummy preos: </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">args</span><span class="p">))</span>
</pre></div>
</div>
<p>When you try to run this new preos you will get:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ cdist preos -h
Available PreOS-es:
- debian
- devuan
- freebsd
- ubuntu
$ cdist preos freebsd
FreeBSD dummy preos: <span class="o">[]</span>
</pre></div>
</div>
<p>In the <code class="docutils literal notranslate"><span class="pre">commandline</span></code> function/method you have all the freedom to actually create
a PreOS.</p>
</div>
</div>
</div>
<div class="section" id="simple-tipical-use-case-for-using-preos-and-trigger">
<h2><span class="section-number">22.4. </span>Simple tipical use case for using PreOS and trigger<a class="headerlink" href="#simple-tipical-use-case-for-using-preos-and-trigger" title="Permalink to this headline"></a></h2>
<p>Tipical use case for using PreOS and trigger command include the following steps.</p>
<ol class="arabic">
<li><p>Create PreOS PXE with ssh key and trigger command for installation.</p>
<blockquote>
<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ cdist preos ubuntu /preos/ubuntu -b -C <span class="se">\</span>
-k ~/.ssh/id_rsa.pub -p /preos/pxe <span class="se">\</span>
-t <span class="s2">&quot;/usr/bin/curl 192.168.111.5:3000/cdist/install/&quot;</span>
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Configure dhcp server and tftp server.</p></li>
<li><p>On cdist host (192.168.111.5 from above) start trigger command (it will use
default init manifest for installation).</p>
<blockquote>
<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ cdist trigger -b -v
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>After all is set up start new machines (PXE boot).</p></li>
<li><p>New machine boots and executes trigger command, i.e. triggers installation.</p></li>
<li><p>Cdist trigger server starts installing host that has triggered it.</p></li>
<li><p>After cdist install is finished new host is installed.</p></li>
</ol>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="cdist-integration.html" class="btn btn-neutral float-right" title="23. cdist integration / using cdist as library" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="cdist-trigger.html" class="btn btn-neutral float-left" title="21. Trigger" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright ungleich GmbH 2020
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>