mirror of
https://github.com/kernelkit/infix.git
synced 2026-08-01 05:13:01 +02:00
Deployed ff909275 to dev with MkDocs 1.6.1 and mike 2.1.3
This commit is contained in:
github-actions[bot]
+151
-116
@@ -989,6 +989,30 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Failure Modes">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#vpd-fail" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
VPD Fail
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#broken-startup-config" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
Broken startup-config
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -1739,6 +1763,30 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Failure Modes">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#vpd-fail" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
VPD Fail
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#broken-startup-config" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
Broken startup-config
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -1880,37 +1928,31 @@
|
||||
<p>Systems running Infix will typically boot in multiple phases, forming
|
||||
a boot chain. Each link in the chain has three main responsibilities:</p>
|
||||
<ol>
|
||||
<li>
|
||||
<p>Ensuring the integrity of the next link before passing control to
|
||||
it. This avoids silent failures stemming from data corruption.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Ensuring the authenticity of the next link before passing control
|
||||
<li>Ensuring the integrity of the next link before passing control to
|
||||
it. This avoids silent failures stemming from data corruption.</li>
|
||||
<li>Ensuring the authenticity of the next link before passing control
|
||||
to it, commonly referred to as <em>Secure Boot</em>. This protects against
|
||||
malicious attempts to modify a system's firmware.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Preparing the system state according to the requirements of the
|
||||
malicious attempts to modify a system's firmware.</li>
|
||||
<li>Preparing the system state according to the requirements of the
|
||||
next link. E.g. the Linux kernel requires the system's RAM to be
|
||||
operational.</p>
|
||||
</li>
|
||||
operational.</li>
|
||||
</ol>
|
||||
<p>A typical chain consists of four stages:</p>
|
||||
<div class="highlight"><pre><span></span><code> .---------.
|
||||
| ROM >---. Determine the location of and load the SPL
|
||||
'---------' |
|
||||
.-----------------'
|
||||
| .---------.
|
||||
'---> SPL >---. Perform DDR training and load the TPL
|
||||
'---------' |
|
||||
.-----------------'
|
||||
| .---------.
|
||||
'---> TPL >---. Load Linux kernel, device tree, and root filesystem
|
||||
'---------' |
|
||||
.-----------------'
|
||||
| .---------.
|
||||
'---> Infix | Get down to business
|
||||
'---------'
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a> .---------.
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> | ROM >---. Determine the location of and load the SPL
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> '---------' |
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>.-----------------'
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>| .---------.
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>'---> SPL >---. Perform DDR training and load the TPL
|
||||
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> '---------' |
|
||||
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>.-----------------'
|
||||
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>| .---------.
|
||||
<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>'---> TPL >---. Load Linux kernel, device tree, and root filesystem
|
||||
<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a> '---------' |
|
||||
<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>.-----------------'
|
||||
<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>| .---------.
|
||||
<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>'---> Infix | Get down to business
|
||||
<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a> '---------'
|
||||
</code></pre></div>
|
||||
<p>After a reset, hardware will pass control to a program (<em>ROM</em>) which
|
||||
is almost always programmed into the SoC by the vendor. This program
|
||||
@@ -1932,20 +1974,19 @@ described by existing documentation provided by the SoC vendor.</p>
|
||||
<p>To mitigate the risk of a malicious user being able to circumvent the
|
||||
bootloader's validation procedure, user configuration is kept to a
|
||||
minimum. Two settings are available:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<p><strong>Boot order</strong>: Since Infix maintains two copies of its software image,
|
||||
and as some bootloaders support <a href="../netboot/">netbooting</a>, the order in which boot
|
||||
sources are considered can be configured. To select the active
|
||||
source, use <a href="https://rauc.io">RAUC</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code>rauc status mark-active <slot>
|
||||
and as some bootloaders support <a href="../netboot/">netbooting</a>, the order in which boot
|
||||
sources are considered can be configured. To select the active
|
||||
source, use <a href="https://rauc.io">RAUC</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>root@example:~# rauc status mark-active <slot>
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>Where <code><slot></code> is one of:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th><code><slot></code></th>
|
||||
<th>Source</th>
|
||||
<th><strong><code><slot></code></strong></th>
|
||||
<th><strong>Source</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -1963,19 +2004,17 @@ minimum. Two settings are available:</p>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>Debug</strong>: By default, the kernel will only output errors to the
|
||||
console during boot. Optionally, this can be altered such that all
|
||||
enabled messages are logged.</p>
|
||||
</li>
|
||||
</ul>
|
||||
console during boot. Optionally, this can be altered such that all
|
||||
enabled messages are logged.</p>
|
||||
<p>On systems using <em>U-Boot</em>, this can be enabled by running <code>fw_setenv
|
||||
DEBUG 1</code>. To restore the default behavior, run <code>fw_setenv DEBUG</code>.</p>
|
||||
<p>On systems running <em>GRUB</em>, this can be enabled by running
|
||||
<code>grub-editenv /mnt/aux/grub/grubenv set DEBUG=1</code>. To restore the
|
||||
default behavior, run <code>grub-editenv /mnt/aux/grub/grubenv unset
|
||||
DEBUG</code></p>
|
||||
DEBUG 1</code>. To restore the default behavior, run <code>fw_setenv DEBUG</code>.</p>
|
||||
<p>On systems running <em>GRUB</em>, this can be enabled by running:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>root@example:~# grub-editenv /mnt/aux/grub/grubenv set DEBUG=1
|
||||
</code></pre></div>
|
||||
<p>To restore the default behavior, run:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>root@example:~# grub-editenv /mnt/aux/grub/grubenv unset DEBUG
|
||||
</code></pre></div>
|
||||
<h3 id="u-boot">U-Boot<a class="headerlink" href="#u-boot" title="Permanent link">¶</a></h3>
|
||||
<p>Used on <em>aarch64</em> based systems. It is able to verify both the
|
||||
<em>integrity</em> and <em>authenticity</em> of an Infix image. As such, it can be
|
||||
@@ -2007,45 +2046,46 @@ password in VPD, are detailed later in this section.</p>
|
||||
<p><img alt="System boot flowchart" src="../img/fail-secure.svg" /></p>
|
||||
<ol>
|
||||
<li>Before mounting <code>/cfg</code> and <code>/var</code> partitions, hosting read-writable
|
||||
data like <code>startup-config</code> and container images, the system first
|
||||
checks if a factory reset has been requested by the user, if so it
|
||||
wipes the contents of these partitions</li>
|
||||
data like <code>startup-config</code> and container images, the system first
|
||||
checks if a factory reset has been requested by the user, if so it
|
||||
wipes the contents of these partitions</li>
|
||||
<li>Linux boots with a device tree which is used for detecting generic
|
||||
make and model of the device, e.g., number of interfaces. It may
|
||||
also reference an EEPROM with <a href="../vpd/">Vital Product Data</a>. That is
|
||||
where the base MAC address and per-device password hash is stored.
|
||||
(Generic builds use the same MAC address and password)</li>
|
||||
make and model of the device, e.g., number of interfaces. It may
|
||||
also reference an EEPROM with <a href="../vpd/">Vital Product Data</a>. That is
|
||||
where the base MAC address and per-device password hash is stored.
|
||||
(Generic builds use the same MAC address and password)</li>
|
||||
<li>On every boot the system's <code>factory-config</code> and <code>failure-config</code> are
|
||||
generated from the YANG<sup id="fnref:2"><a class="footnote-ref" href="#fn:2">2</a></sup> models of the current firmware version.
|
||||
This ensures that a factory reset device can always boot, and that
|
||||
there is a working fail safe, or rather <em>fail secure</em>, mode</li>
|
||||
generated from the YANG<sup id="fnref:2"><a class="footnote-ref" href="#fn:2">2</a></sup> models of the current firmware version.
|
||||
This ensures that a factory reset device can always boot, and that
|
||||
there is a working fail safe, or rather <em>fail secure</em>, mode</li>
|
||||
<li>On first power-on, and after a factory reset, the system does not
|
||||
have a <code>startup-config</code>, in which case <code>factory-config</code> is copied
|
||||
to <code>startup-config</code> -- if a per-product specific version exists it
|
||||
is preferred over the generated one</li>
|
||||
have a <code>startup-config</code>, in which case <code>factory-config</code> is copied
|
||||
to <code>startup-config</code> -- if a per-product specific version exists it
|
||||
is preferred over the generated one</li>
|
||||
<li>Provided the integrity of the <code>startup-config</code> is OK, a system
|
||||
service loads and activates the configuration</li>
|
||||
service loads and activates the configuration</li>
|
||||
</ol>
|
||||
<h3 id="failure-modes">Failure Modes<a class="headerlink" href="#failure-modes" title="Permanent link">¶</a></h3>
|
||||
<p>So, what happens if any of the steps above fail?</p>
|
||||
<p><strong>VPD Fail</strong></p>
|
||||
<h4 id="vpd-fail">VPD Fail<a class="headerlink" href="#vpd-fail" title="Permanent link">¶</a></h4>
|
||||
<p>The per-device password cannot be read, or is corrupt, so the system
|
||||
<code>factory-config</code> and <code>failure-config</code> are not generated:</p>
|
||||
<ol>
|
||||
<li>First boot, or after factory reset: <code>startup-config</code> cannot be
|
||||
created or loaded, and <code>failure-config</code> cannot be loaded. The
|
||||
system ends up in an unrecoverable state, i.e., <strong>RMA<sup id="fnref:3"><a class="footnote-ref" href="#fn:3">3</a></sup> Mode</strong></li>
|
||||
created or loaded, and <code>failure-config</code> cannot be loaded. The
|
||||
system ends up in an unrecoverable state, i.e., <strong>RMA<sup id="fnref:3"><a class="footnote-ref" href="#fn:3">3</a></sup> Mode</strong></li>
|
||||
<li>The system has booted (at least) once with correct VPD and password
|
||||
and already has a <code>startup-config</code>. Provided the <code>startup-config</code>
|
||||
is OK (see below), it is loaded and system boots successfully</li>
|
||||
and already has a <code>startup-config</code>. Provided the <code>startup-config</code>
|
||||
is OK (see below), it is loaded and system boots successfully</li>
|
||||
</ol>
|
||||
<p>In both cases, external factory reset modes/button will not help, and
|
||||
in the second case will cause the device to fail on the next boot.</p>
|
||||
<blockquote>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The second case does not yet have any warning or event that can be
|
||||
detected from the outside. This is planned for a later release.</p>
|
||||
</blockquote>
|
||||
<p><strong>Broken startup-config</strong></p>
|
||||
</div>
|
||||
<h4 id="broken-startup-config">Broken startup-config<a class="headerlink" href="#broken-startup-config" title="Permanent link">¶</a></h4>
|
||||
<p>If loading <code>startup-config</code> fails for some reason, e.g., invalid JSON
|
||||
syntax, failed validation against the system's YANG model, or a bug in
|
||||
the system's <code>confd</code> service, the <em>Fail Secure Mode</em> is triggered and
|
||||
@@ -2067,24 +2107,19 @@ the device's base MAC address.</p>
|
||||
<p>Much of the minutiae of software upgrades is delegated to <a href="https://rauc.io">RAUC</a>,
|
||||
which offers lots of benefits out-of-the-box:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Upgrade Bundles are always signed, such that their authenticity can
|
||||
<li>Upgrade Bundles are always signed, such that their authenticity can
|
||||
be verified by the running operating system, before the new one is
|
||||
installed.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>The bureaucracy of interfacing with different bootloaders, manage
|
||||
installed.</li>
|
||||
<li>The bureaucracy of interfacing with different bootloaders, manage
|
||||
the boot order, is a simple matter of providing a compatible
|
||||
configuration.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Updates can be sourced from the local filesystem (including external
|
||||
configuration.</li>
|
||||
<li>Updates can be sourced from the local filesystem (including external
|
||||
media like USB sticks or SD-cards) and from remote servers using FTP
|
||||
or HTTP(S).</p>
|
||||
</li>
|
||||
or HTTP(S).</li>
|
||||
</ul>
|
||||
<p>To initiate a system upgrade from the shell<sup id="fnref:1"><a class="footnote-ref" href="#fn:1">1</a></sup>, run:</p>
|
||||
<div class="highlight"><pre><span></span><code>rauc install <file|url>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>root@example:~# rauc install <file|url>
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>Where the file or URL points to a <a href="#rauc-upgrade-bundle">RAUC Upgrade Bundle</a>.</p>
|
||||
<p>This will upgrade the partition not currently running. After a
|
||||
@@ -2151,34 +2186,34 @@ to use.</p>
|
||||
<p>Infix runs from a block device (e.g. eMMC or virtio disk) with the
|
||||
following layout. The disk is expected to use the GPT partitioning
|
||||
scheme. Partitions marked with an asterisk are optional.</p>
|
||||
<div class="highlight"><pre><span></span><code>.-----------.
|
||||
| GPT Table |
|
||||
:-----------:
|
||||
| boot* |
|
||||
:-----------:
|
||||
| aux |
|
||||
:-----------:
|
||||
| |
|
||||
| primary |
|
||||
| |
|
||||
:-----------:
|
||||
| |
|
||||
| secondary |
|
||||
| |
|
||||
:-----------:
|
||||
| cfg |
|
||||
:-----------:
|
||||
| |
|
||||
| var* |
|
||||
| |
|
||||
'-----------'
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>.-----------.
|
||||
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>| GPT Table |
|
||||
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>:-----------:
|
||||
<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>| boot* |
|
||||
<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>:-----------:
|
||||
<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>| aux |
|
||||
<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a>:-----------:
|
||||
<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a>| |
|
||||
<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a>| primary |
|
||||
<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a>| |
|
||||
<a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a>:-----------:
|
||||
<a id="__codelineno-5-12" name="__codelineno-5-12" href="#__codelineno-5-12"></a>| |
|
||||
<a id="__codelineno-5-13" name="__codelineno-5-13" href="#__codelineno-5-13"></a>| secondary |
|
||||
<a id="__codelineno-5-14" name="__codelineno-5-14" href="#__codelineno-5-14"></a>| |
|
||||
<a id="__codelineno-5-15" name="__codelineno-5-15" href="#__codelineno-5-15"></a>:-----------:
|
||||
<a id="__codelineno-5-16" name="__codelineno-5-16" href="#__codelineno-5-16"></a>| cfg |
|
||||
<a id="__codelineno-5-17" name="__codelineno-5-17" href="#__codelineno-5-17"></a>:-----------:
|
||||
<a id="__codelineno-5-18" name="__codelineno-5-18" href="#__codelineno-5-18"></a>| |
|
||||
<a id="__codelineno-5-19" name="__codelineno-5-19" href="#__codelineno-5-19"></a>| var* |
|
||||
<a id="__codelineno-5-20" name="__codelineno-5-20" href="#__codelineno-5-20"></a>| |
|
||||
<a id="__codelineno-5-21" name="__codelineno-5-21" href="#__codelineno-5-21"></a>'-----------'
|
||||
</code></pre></div>
|
||||
<h4 id="boot-bootloader"><code>boot</code> - Bootloader<a class="headerlink" href="#boot-bootloader" title="Permanent link">¶</a></h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Value</th>
|
||||
<th><strong>Parameter</strong></th>
|
||||
<th><strong>Value</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -2204,8 +2239,8 @@ the GRUB bootloader.</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Value</th>
|
||||
<th><strong>Parameter</strong></th>
|
||||
<th><strong>Value</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -2227,10 +2262,10 @@ the GRUB bootloader.</p>
|
||||
such as image signatures required to validate the chain of trust,
|
||||
bootloader configuration etc.</p>
|
||||
<p>Typical layout when using U-Boot bootloader:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a> /
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> ├ primary.itbh
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> ├ secondary.itbh
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> └ uboot.env
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>/
|
||||
<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>├ primary.itbh
|
||||
<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>├ secondary.itbh
|
||||
<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>└ uboot.env
|
||||
</code></pre></div>
|
||||
<p>During boot, an ITB header along with the corresponding root
|
||||
filesystem image are concatenated in memory, by U-Boot, to form a
|
||||
@@ -2243,8 +2278,8 @@ required to configure the boot order.</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Value</th>
|
||||
<th><strong>Parameter</strong></th>
|
||||
<th><strong>Value</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -2269,8 +2304,8 @@ rollbacks when upgrading to a new version.</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Value</th>
|
||||
<th><strong>Parameter</strong></th>
|
||||
<th><strong>Value</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -2294,8 +2329,8 @@ Concretely, user data is everything stored under <code>/root</code> and <code>/h
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Value</th>
|
||||
<th><strong>Parameter</strong></th>
|
||||
<th><strong>Value</strong></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
+244
-156
@@ -1331,6 +1331,48 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Example Snippets">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-system" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF System
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-keystore" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF Keystore
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-netconf-server" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF NETCONF Server
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#infix-services" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
Infix Services
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -1682,6 +1724,48 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Example Snippets">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-system" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF System
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-keystore" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF Keystore
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ietf-netconf-server" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
IETF NETCONF Server
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#infix-services" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
Infix Services
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -1775,7 +1859,8 @@
|
||||
|
||||
|
||||
<h1 id="branding-releases">Branding & Releases<a class="headerlink" href="#branding-releases" title="Permanent link">¶</a></h1>
|
||||
<p>This document is for projects using Infix as a br2-external, i.e., OEMs.</p>
|
||||
<p>This document is for projects using Infix as a br2-external, i.e., OEMs
|
||||
that want to create *their own "Spin" of Infix.</p>
|
||||
<h2 id="branding">Branding<a class="headerlink" href="#branding" title="Permanent link">¶</a></h2>
|
||||
<p>Branding is done in menuconfig, there are several settings affecting
|
||||
it, most are in the Infix external subsection called "Branding", but
|
||||
@@ -1792,17 +1877,17 @@ check this for you and you may end up with odd results.</p>
|
||||
<p>Verify the result after a build by inspecting:</p>
|
||||
<ul>
|
||||
<li><code>output/images/*</code>: names, missing prefix, etc.</li>
|
||||
<li><code>output/target/etc/os-release</code>: this file is sourced by
|
||||
other build scripts, e.g., <code>mkgns3a.sh</code>. For reference, see
|
||||
https://www.freedesktop.org/software/systemd/man/os-release.html</li>
|
||||
<li><code>output/target/etc/os-release</code>: this file is sourced by other build
|
||||
scripts, e.g., <code>mkgns3a.sh</code>. For reference, see <a href="https://www.freedesktop.org/software/systemd/man/os-release.html">os-release(5)</a></li>
|
||||
</ul>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> to get proper GIT revision (hash) from your composed OS,
|
||||
remember in menuconfig to set <code>INFIX_OEM_PATH</code>. When unset the
|
||||
Infix <code>post-build.sh</code> script defaults to the Infix base path. The
|
||||
revision is stored in the file <code>/etc/os-release</code> as BUILD_ID and
|
||||
is also in the file <code>/etc/version</code>. See below for more info.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>To get a proper GIT revision (hash) from your OS spin, remember to set
|
||||
in menuconfig <code>INFIX_OEM_PATH</code>. When unset, the Infix <code>post-build.sh</code>
|
||||
script defaults to the Infix base path. The revision is stored in the
|
||||
file <code>/etc/os-release</code> as <code>BUILD_ID</code>, also in the file <code>/etc/version</code>.
|
||||
See below for more info.</p>
|
||||
</div>
|
||||
<h2 id="factory-failure-config">Factory & Failure Config<a class="headerlink" href="#factory-failure-config" title="Permanent link">¶</a></h2>
|
||||
<p>To support booting the same image (CPU architecture) on multiple boards,
|
||||
Infix by default generates the device's initial configuration every time
|
||||
@@ -1822,22 +1907,23 @@ available keywords, see the next section for examples of how to use
|
||||
them:</p>
|
||||
<ul>
|
||||
<li><strong>Default password hash:</strong> <code>$factory$</code> (from VPD, .dtb, or built-in)<br />
|
||||
XPath: <code>/ietf-system:system/authentication/user/password</code></li>
|
||||
XPath: <code>/ietf-system:system/authentication/user/password</code></li>
|
||||
<li><strong>Default SSH and NETCONF hostkey:</strong> <code>genkey</code> (regenerated at factory reset)
|
||||
XPath: <code>/ietf-keystore:keystore/asymmetric-keys/asymmetric-key[name='genkey']</code></li>
|
||||
XPath: <code>/ietf-keystore:keystore/asymmetric-keys/asymmetric-key[name='genkey']</code></li>
|
||||
<li><strong>Hostname format specifiers:</strong><br />
|
||||
XPath: <code>/ietf-system:system/hostname</code></li>
|
||||
XPath: <code>/ietf-system:system/hostname</code></li>
|
||||
<li><code>%i</code>: OS ID, from <code>/etc/os-release</code>, from Menuconfig branding</li>
|
||||
<li><code>%h</code>: Default hostname, from <code>/etc/os-release</code>, from branding</li>
|
||||
<li><code>%m</code>: NIC specific part of base MAC, e.g., to <code>c0-ff-ee</code></li>
|
||||
<li><code>%%</code>: Literal %</li>
|
||||
</ul>
|
||||
<h3 id="static-files">Static Files<a class="headerlink" href="#static-files" title="Permanent link">¶</a></h3>
|
||||
<blockquote>
|
||||
<p><strong>Caveat:</strong> maintaining static a factory-config and failure-config may
|
||||
seem like an obvious choice, but as YANG models evolve (even the IETF
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>Maintaining a static <code>factory-config</code> and <code>failure-config</code> may seem
|
||||
like an obvious choice, but as YANG models evolve (even the IETF
|
||||
models get upgraded), you may need to upgrade your static files.</p>
|
||||
</blockquote>
|
||||
</div>
|
||||
<p>First, for one-off builds (one image per product), the simplest way is
|
||||
to override the location where the system looks for the files, <code>/etc</code>
|
||||
already at build time. This can be done using a Buildroot rootfs
|
||||
@@ -1879,28 +1965,28 @@ last three octets of the system's base MAC address. To override the
|
||||
base hostname, set <code>BR2_TARGET_GENERIC_HOSTNAME</code> in your defconfig.</p>
|
||||
<p>The static files are installed by Infix <code>confd</code> in <code>/usr/share/confd/</code>
|
||||
at build time. It contains two subdirectories:</p>
|
||||
<div class="highlight"><pre><span></span><code>/usr/share/confd/
|
||||
|- factory.d/
|
||||
| |- 10-foo.json
|
||||
| |- 10-bar.json
|
||||
| `- 10-qux.json
|
||||
`- failure.d/
|
||||
|- 10-xyzzy.json
|
||||
`- 10-garply.json
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>/usr/share/confd/
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> |- factory.d/
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> | |- 10-foo.json
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> | |- 10-bar.json
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> | `- 10-qux.json
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> `- failure.d/
|
||||
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> |- 10-xyzzy.json
|
||||
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> `- 10-garply.json
|
||||
</code></pre></div>
|
||||
<p>To override, or extend, these files in you br2-external, set up a rootfs
|
||||
overlay and add it last in <code>BR2_ROOTFS_OVERLAY</code>. Your overlay can look
|
||||
something like this:</p>
|
||||
<div class="highlight"><pre><span></span><code>./board/common/rootfs/
|
||||
|- etc/
|
||||
| |- confdrc # See below
|
||||
| `- confdrc.local
|
||||
`- usr/
|
||||
`- share/
|
||||
`- confd/
|
||||
|- 10-foo.json # Override Infix foo
|
||||
|- 30-bar.json # Extend, probably 10-bar.json
|
||||
`- 30-fred.json # Extend, your own defaults
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>./board/common/rootfs/
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a> |- etc/
|
||||
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a> | |- confdrc # See below
|
||||
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a> | `- confdrc.local
|
||||
<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a> `- usr/
|
||||
<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a> `- share/
|
||||
<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a> `- confd/
|
||||
<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a> |- 10-foo.json # Override Infix foo
|
||||
<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a> |- 30-bar.json # Extend, probably 10-bar.json
|
||||
<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a> `- 30-fred.json # Extend, your own defaults
|
||||
</code></pre></div>
|
||||
<p>Using the same filename in your overlay, here <code>10-foo.json</code>, completely
|
||||
replaces the contents of the same file provided by Infix. If you just
|
||||
@@ -1912,122 +1998,123 @@ generated by Infix' <code>gen-function</code> scripts. Your br2-external can
|
||||
provide a few custom ones that the <code>bootstrap</code> knows about, e.g.,
|
||||
<code>gen-ifs-custom</code> that overrides <code>20-interfaces.json</code>. See the
|
||||
bootstrap script for more help, and up-to-date information.</p>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> you may not need to provide your own <code>/etc/confdrc</code>. The
|
||||
one installed by <code>confd</code> is usually enough. However, if you want to
|
||||
adjust the behavior of <code>bootstrap</code> you may want to override it. There
|
||||
is also <code>confdrc.local</code>, which usually is enough to change arguments
|
||||
to scripts like <code>gen-interfaces</code>, e.g., to create a bridge by default,
|
||||
you may want to look into <code>GEN_IFACE_OPTS</code>.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>You may not need to provide your own <code>/etc/confdrc</code> for your spin.
|
||||
The one installed by <code>confd</code> is usually enough. However, if you want
|
||||
to adjust the behavior of <code>bootstrap</code> you may want to override it.
|
||||
There is also <code>confdrc.local</code>, which usually is enough to change
|
||||
arguments to scripts like <code>gen-interfaces</code>, e.g., to create a bridge
|
||||
by default, you may want to look into <code>GEN_IFACE_OPTS</code>.</p>
|
||||
</div>
|
||||
<h3 id="example-snippets">Example Snippets<a class="headerlink" href="#example-snippets" title="Permanent link">¶</a></h3>
|
||||
<p><strong>IETF System:</strong></p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a> "ietf-system:system": {
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> "hostname": "example-%m",
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> "ntp": {
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> "enabled": true,
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> "server": [
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> {
|
||||
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> "name": "ntp.org",
|
||||
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> "udp": {
|
||||
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> "address": "pool.ntp.org"
|
||||
<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a> }
|
||||
<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a> }
|
||||
<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a> ]
|
||||
<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a> },
|
||||
<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a> "authentication": {
|
||||
<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a> "user": [
|
||||
<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a> {
|
||||
<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a> "name": "admin",
|
||||
<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a> "password": "$factory$",
|
||||
<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a> "infix-system:shell": "bash"
|
||||
<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a> }
|
||||
<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a> ]
|
||||
<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a> },
|
||||
<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a> "infix-system:motd-banner": "Li0tLS0tLS0uCnwgIC4gLiAgfCBJbmZpeCAtLSBhIE5ldHdvcmsgT3BlcmF0aW5nIFN5c3RlbQp8LS4gdiAuLXwgaHR0cHM6Ly9rZXJuZWxraXQuZ2l0aHViLmlvCictJy0tLSctJwo="
|
||||
<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a> }, # <---- REMEMBER COMMA SEPARATORS IN SNIPPETS!
|
||||
<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a> # <---- ... and no comments.
|
||||
<h4 id="ietf-system">IETF System<a class="headerlink" href="#ietf-system" title="Permanent link">¶</a></h4>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a> "ietf-system:system": {
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a> "hostname": "example-%m",
|
||||
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a> "ntp": {
|
||||
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a> "enabled": true,
|
||||
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> "server": [
|
||||
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> {
|
||||
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> "name": "ntp.org",
|
||||
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a> "udp": {
|
||||
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a> "address": "pool.ntp.org"
|
||||
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a> }
|
||||
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a> }
|
||||
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a> ]
|
||||
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a> },
|
||||
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a> "authentication": {
|
||||
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a> "user": [
|
||||
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a> {
|
||||
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a> "name": "admin",
|
||||
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a> "password": "$factory$",
|
||||
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> "infix-system:shell": "bash"
|
||||
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> }
|
||||
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a> ]
|
||||
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> },
|
||||
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a> "infix-system:motd-banner": "Li0tLS0tLS0uCnwgIC4gLiAgfCBJbmZpeCAtLSBhIE5ldHdvcmsgT3BlcmF0aW5nIFN5c3RlbQp8LS4gdiAuLXwgaHR0cHM6Ly9rZXJuZWxraXQuZ2l0aHViLmlvCictJy0tLSctJwo="
|
||||
<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a> }, # <---- REMEMBER COMMA SEPARATORS IN SNIPPETS!
|
||||
<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a> # <---- ... and no comments.
|
||||
</code></pre></div>
|
||||
<p>The <code>motd-banner</code> is a binary type, which is basically a Base64 encoded
|
||||
text file without line breaks (<code>-w0</code>):</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>$<span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">"Li0tLS0tLS0uCnwgIC4gLiAgfCBJbmZpeCAtLSBhIE5ldHdvcmsgT3BlcmF0aW5nIFN5c3RlbQp8LS4gdiAuLXwgaHR0cHM6Ly9rZXJuZWxraXQuZ2l0aHViLmlvCictJy0tLSctJwo="</span><span class="w"> </span><span class="p">|</span>base64<span class="w"> </span>-d
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>.-------.
|
||||
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="p">|</span><span class="w"> </span>.<span class="w"> </span>.<span class="w"> </span><span class="p">|</span><span class="w"> </span>Infix<span class="w"> </span>OS<span class="w"> </span>—<span class="w"> </span>Immutable.Friendly.Secure
|
||||
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="p">|</span>-.<span class="w"> </span>v<span class="w"> </span>.-<span class="p">|</span><span class="w"> </span>https://kernelkit.github.io
|
||||
<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="s1">'-'</span>---<span class="s1">'-'</span>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>$<span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">"Li0tLS0tLS0uCnwgIC4gLiAgfCBJbmZpeCAtLSBhIE5ldHdvcmsgT3BlcmF0aW5nIFN5c3RlbQp8LS4gdiAuLXwgaHR0cHM6Ly9rZXJuZWxraXQuZ2l0aHViLmlvCictJy0tLSctJwo="</span><span class="w"> </span><span class="p">|</span>base64<span class="w"> </span>-d
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>.-------.
|
||||
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="p">|</span><span class="w"> </span>.<span class="w"> </span>.<span class="w"> </span><span class="p">|</span><span class="w"> </span>Infix<span class="w"> </span>OS<span class="w"> </span>—<span class="w"> </span>Immutable.Friendly.Secure
|
||||
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="p">|</span>-.<span class="w"> </span>v<span class="w"> </span>.-<span class="p">|</span><span class="w"> </span>https://kernelkit.github.io
|
||||
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="s1">'-'</span>---<span class="s1">'-'</span>
|
||||
</code></pre></div>
|
||||
<p><strong>IETF Keystore</strong></p>
|
||||
<h4 id="ietf-keystore">IETF Keystore<a class="headerlink" href="#ietf-keystore" title="Permanent link">¶</a></h4>
|
||||
<p>Notice how both the public and private keys are left empty here, this
|
||||
cause them to be always automatically regenerated after each factory reset.
|
||||
Keeping the <code>factory-config</code> snippet like this means we can use the same
|
||||
file on multiple devices, without risking them sharing the same host
|
||||
keys. Sometimes you may want the same host keys, but that is the easy
|
||||
use-case and not documented here.</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="w"> </span><span class="nt">"ietf-keystore:keystore"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">"asymmetric-keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">"asymmetric-key"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"genkey"</span><span class="p">,</span>
|
||||
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w"> </span><span class="nt">"public-key-format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ietf-crypto-types:ssh-public-key-format"</span><span class="p">,</span>
|
||||
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="w"> </span><span class="nt">"public-key"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||||
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span><span class="nt">"private-key-format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ietf-crypto-types:rsa-private-key-format"</span><span class="p">,</span>
|
||||
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="w"> </span><span class="nt">"cleartext-private-key"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||||
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="w"> </span><span class="nt">"certificates"</span><span class="p">:</span><span class="w"> </span><span class="p">{}</span>
|
||||
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a><span class="w"> </span><span class="p">},</span>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="w"> </span><span class="nt">"ietf-keystore:keystore"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span><span class="nt">"asymmetric-keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span><span class="nt">"asymmetric-key"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"genkey"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w"> </span><span class="nt">"public-key-format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ietf-crypto-types:ssh-public-key-format"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w"> </span><span class="nt">"public-key"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w"> </span><span class="nt">"private-key-format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ietf-crypto-types:rsa-private-key-format"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w"> </span><span class="nt">"cleartext-private-key"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="w"> </span><span class="nt">"certificates"</span><span class="p">:</span><span class="w"> </span><span class="p">{}</span>
|
||||
<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-4-12" name="__codelineno-4-12" href="#__codelineno-4-12"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-4-13" name="__codelineno-4-13" href="#__codelineno-4-13"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-4-14" name="__codelineno-4-14" href="#__codelineno-4-14"></a><span class="w"> </span><span class="p">},</span>
|
||||
</code></pre></div>
|
||||
<p><strong>IETF NETCONF Server</strong></p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="w"> </span><span class="nt">"ietf-netconf-server:netconf-server"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w"> </span><span class="nt">"listen"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w"> </span><span class="nt">"endpoints"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="w"> </span><span class="nt">"endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"default-ssh"</span><span class="p">,</span>
|
||||
<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="w"> </span><span class="nt">"ssh"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="w"> </span><span class="nt">"tcp-server-parameters"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a><span class="w"> </span><span class="nt">"local-address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"::"</span>
|
||||
<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="w"> </span><span class="p">},</span>
|
||||
<a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a><span class="w"> </span><span class="nt">"ssh-server-parameters"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a><span class="w"> </span><span class="nt">"server-identity"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a><span class="w"> </span><span class="nt">"host-key"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"default-key"</span><span class="p">,</span>
|
||||
<a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a><span class="w"> </span><span class="nt">"public-key"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w"> </span><span class="nt">"central-keystore-reference"</span><span class="p">:</span><span class="w"> </span><span class="s2">"genkey"</span>
|
||||
<a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-3-21" name="__codelineno-3-21" href="#__codelineno-3-21"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-22" name="__codelineno-3-22" href="#__codelineno-3-22"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-23" name="__codelineno-3-23" href="#__codelineno-3-23"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-24" name="__codelineno-3-24" href="#__codelineno-3-24"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-25" name="__codelineno-3-25" href="#__codelineno-3-25"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-3-26" name="__codelineno-3-26" href="#__codelineno-3-26"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-27" name="__codelineno-3-27" href="#__codelineno-3-27"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-3-28" name="__codelineno-3-28" href="#__codelineno-3-28"></a><span class="w"> </span><span class="p">},</span>
|
||||
<h4 id="ietf-netconf-server">IETF NETCONF Server<a class="headerlink" href="#ietf-netconf-server" title="Permanent link">¶</a></h4>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="w"> </span><span class="nt">"ietf-netconf-server:netconf-server"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span><span class="nt">"listen"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w"> </span><span class="nt">"endpoints"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w"> </span><span class="nt">"endpoint"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"default-ssh"</span><span class="p">,</span>
|
||||
<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w"> </span><span class="nt">"ssh"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="w"> </span><span class="nt">"tcp-server-parameters"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="w"> </span><span class="nt">"local-address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"::"</span>
|
||||
<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="w"> </span><span class="p">},</span>
|
||||
<a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a><span class="w"> </span><span class="nt">"ssh-server-parameters"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-12" name="__codelineno-5-12" href="#__codelineno-5-12"></a><span class="w"> </span><span class="nt">"server-identity"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-13" name="__codelineno-5-13" href="#__codelineno-5-13"></a><span class="w"> </span><span class="nt">"host-key"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-5-14" name="__codelineno-5-14" href="#__codelineno-5-14"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-15" name="__codelineno-5-15" href="#__codelineno-5-15"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"default-key"</span><span class="p">,</span>
|
||||
<a id="__codelineno-5-16" name="__codelineno-5-16" href="#__codelineno-5-16"></a><span class="w"> </span><span class="nt">"public-key"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-5-17" name="__codelineno-5-17" href="#__codelineno-5-17"></a><span class="w"> </span><span class="nt">"central-keystore-reference"</span><span class="p">:</span><span class="w"> </span><span class="s2">"genkey"</span>
|
||||
<a id="__codelineno-5-18" name="__codelineno-5-18" href="#__codelineno-5-18"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-19" name="__codelineno-5-19" href="#__codelineno-5-19"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-20" name="__codelineno-5-20" href="#__codelineno-5-20"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-5-21" name="__codelineno-5-21" href="#__codelineno-5-21"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-22" name="__codelineno-5-22" href="#__codelineno-5-22"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-23" name="__codelineno-5-23" href="#__codelineno-5-23"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-24" name="__codelineno-5-24" href="#__codelineno-5-24"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-25" name="__codelineno-5-25" href="#__codelineno-5-25"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-5-26" name="__codelineno-5-26" href="#__codelineno-5-26"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-27" name="__codelineno-5-27" href="#__codelineno-5-27"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-5-28" name="__codelineno-5-28" href="#__codelineno-5-28"></a><span class="w"> </span><span class="p">},</span>
|
||||
</code></pre></div>
|
||||
<h4 id="infix-services">Infix Services<a class="headerlink" href="#infix-services" title="Permanent link">¶</a></h4>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="w"> </span><span class="nt">"infix-services:ssh"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="w"> </span><span class="nt">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="w"> </span><span class="nt">"hostkey"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="w"> </span><span class="s2">"genkey"</span>
|
||||
<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="w"> </span><span class="p">],</span>
|
||||
<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="w"> </span><span class="nt">"listen"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ipv4"</span><span class="p">,</span>
|
||||
<a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a><span class="w"> </span><span class="nt">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.0.0.0"</span><span class="p">,</span>
|
||||
<a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a><span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">22</span>
|
||||
<a id="__codelineno-6-11" name="__codelineno-6-11" href="#__codelineno-6-11"></a><span class="w"> </span><span class="p">},</span>
|
||||
<a id="__codelineno-6-12" name="__codelineno-6-12" href="#__codelineno-6-12"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-6-13" name="__codelineno-6-13" href="#__codelineno-6-13"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ipv6"</span><span class="p">,</span>
|
||||
<a id="__codelineno-6-14" name="__codelineno-6-14" href="#__codelineno-6-14"></a><span class="w"> </span><span class="nt">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"::1"</span><span class="p">,</span>
|
||||
<a id="__codelineno-6-15" name="__codelineno-6-15" href="#__codelineno-6-15"></a><span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">22</span>
|
||||
<a id="__codelineno-6-16" name="__codelineno-6-16" href="#__codelineno-6-16"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-6-17" name="__codelineno-6-17" href="#__codelineno-6-17"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-6-18" name="__codelineno-6-18" href="#__codelineno-6-18"></a><span class="w"> </span><span class="p">}</span>
|
||||
</code></pre></div>
|
||||
<p><strong>Infix Services</strong>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="w"> </span><span class="nt">"infix-services:ssh"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span><span class="nt">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span><span class="nt">"hostkey"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w"> </span><span class="s2">"genkey"</span>
|
||||
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w"> </span><span class="p">],</span>
|
||||
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w"> </span><span class="nt">"listen"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ipv4"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w"> </span><span class="nt">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.0.0.0"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">22</span>
|
||||
<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="w"> </span><span class="p">},</span>
|
||||
<a id="__codelineno-4-12" name="__codelineno-4-12" href="#__codelineno-4-12"></a><span class="w"> </span><span class="p">{</span>
|
||||
<a id="__codelineno-4-13" name="__codelineno-4-13" href="#__codelineno-4-13"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ipv6"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-14" name="__codelineno-4-14" href="#__codelineno-4-14"></a><span class="w"> </span><span class="nt">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"::1"</span><span class="p">,</span>
|
||||
<a id="__codelineno-4-15" name="__codelineno-4-15" href="#__codelineno-4-15"></a><span class="w"> </span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">22</span>
|
||||
<a id="__codelineno-4-16" name="__codelineno-4-16" href="#__codelineno-4-16"></a><span class="w"> </span><span class="p">}</span>
|
||||
<a id="__codelineno-4-17" name="__codelineno-4-17" href="#__codelineno-4-17"></a><span class="w"> </span><span class="p">]</span>
|
||||
<a id="__codelineno-4-18" name="__codelineno-4-18" href="#__codelineno-4-18"></a><span class="w"> </span><span class="p">}</span>
|
||||
</code></pre></div></p>
|
||||
<h2 id="integration">Integration<a class="headerlink" href="#integration" title="Permanent link">¶</a></h2>
|
||||
<p>When integrating your software stack with Infix there may be protocols
|
||||
that want to change system settings like hostname and dynamically set
|
||||
@@ -2043,14 +2130,14 @@ by other "address providers", e.g., PROFINET.</p>
|
||||
<p>Changing properties like hostname should be done by injecting a change
|
||||
into Infix, by for example calling <code>sysrepocfg -Ediff.xml</code>. Here is an
|
||||
example of how to get the current hostname and apply an XML diff:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>root@infix-00-00-00:~# sysrepocfg -X -x "/system/hostname" > hostnm.xml
|
||||
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>root@infix-00-00-00:~# cat hostnm.xml
|
||||
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
|
||||
<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a> <hostname>infix-00-00-00</hostname>
|
||||
<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a></system>
|
||||
<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>root@infix-00-00-00:~# edit hostnm.xml
|
||||
<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a>root@infix-00-00-00:~# sysrepocfg -Ehostnm.xml
|
||||
<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a>root@example:~#
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>root@infix-00-00-00:~# sysrepocfg -X -x "/system/hostname" > hostnm.xml
|
||||
<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>root@infix-00-00-00:~# cat hostnm.xml
|
||||
<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
|
||||
<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a> <hostname>infix-00-00-00</hostname>
|
||||
<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a></system>
|
||||
<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a>root@infix-00-00-00:~# edit hostnm.xml
|
||||
<a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a>root@infix-00-00-00:~# sysrepocfg -Ehostnm.xml
|
||||
<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a>root@example:~#
|
||||
</code></pre></div>
|
||||
<p>Second, perform all changes on <code>running-config</code>, the running datastore.
|
||||
That way you have a clear state to return to if your application needs
|
||||
@@ -2070,7 +2157,7 @@ two states. The <code>startup-config</code> is applied in runlevel S (bootstrap
|
||||
and the system then enters runlevel 2 for normal operation.</p>
|
||||
<p>This allow you to keep a set of functionality that is provided by the
|
||||
underlying system, and another managed by your application. You can
|
||||
of course in your br2-external provide a sysrepo plugin that block
|
||||
of course in your br2-external provide a sysrepo plugin that block
|
||||
operations on certain datastores when your application is enabled.
|
||||
E.g., to prevent changes to startup after initial deployment. In
|
||||
that case a proper factory reset would be needed to get back to a
|
||||
@@ -2083,23 +2170,24 @@ let us talk about versioning in general.</p>
|
||||
<p>Two popular scheme for versioning a product derived from Infix:</p>
|
||||
<ol>
|
||||
<li>Track Infix major.minor, e.g. <em>Foobar v23.08.z</em>, where <code>z</code> is
|
||||
your patch level. I.e., Foobar v23.08.0 could be based on Infix
|
||||
v23.08.0, or v23.08.12, it is up to you. Maybe you based it on
|
||||
v23.08.12 and then back ported changes from v23.10.0, but it was
|
||||
the first release you made to your customer(s).</li>
|
||||
your patch level. I.e., Foobar v23.08.0 could be based on Infix
|
||||
v23.08.0, or v23.08.12, it is up to you. Maybe you based it on
|
||||
v23.08.12 and then back ported changes from v23.10.0, but it was
|
||||
the first release you made to your customer(s).</li>
|
||||
<li>Start from v1.0.0 and step the major number every time you sync
|
||||
with a new Infix release, or every time Infix bumps to the next
|
||||
Buildroot LTS.</li>
|
||||
with a new Infix release, or every time Infix bumps to the next
|
||||
Buildroot LTS.</li>
|
||||
</ol>
|
||||
<p>The important thing is to be consistent, not only for your own sake,
|
||||
but also for your end customers. The <em>major.minor.patch</em> style is
|
||||
the most common and often recommended style, which usually maps well
|
||||
to other systems, e.g. PROFINET GSDML files require this (<em>VX.Y.Z</em>).
|
||||
But you can of course use only two numbers, <em>major.minor</em>, as well.</p>
|
||||
<blockquote>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>What could be confusing, however, is if you use the name <em>Infix</em>
|
||||
with your own versioning scheme.</p>
|
||||
</blockquote>
|
||||
</div>
|
||||
<h3 id="specifying-versioning-information">Specifying Versioning Information<a class="headerlink" href="#specifying-versioning-information" title="Permanent link">¶</a></h3>
|
||||
<p>Two optional environment variables control the version information
|
||||
recorded in images. Both of these <strong>must be</strong> a lower-case string (no
|
||||
|
||||
@@ -1641,11 +1641,12 @@ bus, here is an example:</p>
|
||||
locked, all connected devices will get power, but never authorized by
|
||||
Linux to use.</p>
|
||||
<h3 id="configure-usb-port">Configure USB port<a class="headerlink" href="#configure-usb-port" title="Permanent link">¶</a></h3>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> You can only configure USB ports known to the system. See
|
||||
<code>show hardware</code> in admin-exec context. (Use <code>do</code> prefix in configure
|
||||
context.)</p>
|
||||
</blockquote>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>You can only configure USB ports known to the system. See the CLI
|
||||
command <code>show hardware</code> in admin-exec context. (Use <code>do</code> prefix in
|
||||
configure context.)</p>
|
||||
</div>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>admin@example:/> configure
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>admin@example:/config/> set hardware component USB state admin-state unlocked
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>admin@example:/config/> leave
|
||||
|
||||
File diff suppressed because one or more lines are too long
+36
-36
@@ -2,146 +2,146 @@
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/boot/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/branding/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/container/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/developers-guide/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/dhcp/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/discovery/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/eth-counters/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/hardware/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/license/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/management/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/netboot/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/networking/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/override-package/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/qos/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/scripting-prod/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/scripting-restconf/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/scripting-sysrepocfg/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/scripting/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/syslog/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/system/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/test-arch/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/testing/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/tunnels/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/upgrade/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/virtual/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/vpd/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/wifi/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/configure/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/introduction/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/keybindings/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/netcalc/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/quick/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/tcpdump/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/text-editor/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://kernelkit.github.io/infix/dev/cli/upgrade/</loc>
|
||||
<lastmod>2025-07-30</lastmod>
|
||||
<lastmod>2025-08-07</lastmod>
|
||||
</url>
|
||||
</urlset>
|
||||
Binary file not shown.
+96
-92
@@ -1649,93 +1649,96 @@ disk, meaning logs are not retained across reboots. This document
|
||||
details how to log to external media or remote syslog servers.</p>
|
||||
<p>It is also possible to set up the device to act as a syslog server (log
|
||||
sink), this is covered briefly at the very end of this document.</p>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> the native logging cannot be modified, only the log file
|
||||
rotation can be changed. Please see the <code>dir</code> admin-exec command for
|
||||
a listing of existing native log files.</p>
|
||||
</blockquote>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The default logging setup in the system cannot be modified, only the
|
||||
log file rotation. Please see the <code>dir</code> admin-exec command for a
|
||||
listing of existing log files.</p>
|
||||
</div>
|
||||
<h2 id="log-to-file">Log to File<a class="headerlink" href="#log-to-file" title="Permanent link">¶</a></h2>
|
||||
<p>Logging to a local file is useful when combined with an external media.
|
||||
E.g., a USB stick with a log partition (named/labeled: "log"). Below is
|
||||
an example.</p>
|
||||
<p>For a list of available log facilities, see the table in a later section.</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>admin@example:/><span class="w"> </span>configure
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>admin@example:/config/syslog/><span class="w"> </span>edit<span class="w"> </span>actions<span class="w"> </span>log-file<span class="w"> </span>file:/media/log/mylog
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="w"> </span>all<span class="w"> </span>audit<span class="w"> </span>auth<span class="w"> </span>authpriv<span class="w"> </span>console<span class="w"> </span>cron<span class="w"> </span>cron2<span class="w"> </span>daemon<span class="w"> </span>ftp<span class="w"> </span>kern
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="w"> </span>local0<span class="w"> </span>local1<span class="w"> </span>local2<span class="w"> </span>local3<span class="w"> </span>local4<span class="w"> </span>local5<span class="w"> </span>local6<span class="w"> </span>local7<span class="w"> </span>lpr<span class="w"> </span>mail
|
||||
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="w"> </span>news<span class="w"> </span>ntp<span class="w"> </span>syslog<span class="w"> </span>user<span class="w"> </span>uucp
|
||||
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list<span class="w"> </span>all<span class="w"> </span>severity
|
||||
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="w"> </span>alert<span class="w"> </span>all<span class="w"> </span>critical<span class="w"> </span>debug<span class="w"> </span>emergency<span class="w"> </span>error<span class="w"> </span>info<span class="w"> </span>none<span class="w"> </span>notice<span class="w"> </span>warning
|
||||
<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list<span class="w"> </span>all<span class="w"> </span>severity<span class="w"> </span>critical
|
||||
<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list<span class="w"> </span>mail<span class="w"> </span>severity<span class="w"> </span>warning
|
||||
<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/><span class="w"> </span>leave
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>admin@example:/> configure
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>admin@example:/config/> edit syslog
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>admin@example:/config/syslog/> edit actions log-file file:/media/log/mylog
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> all audit auth authpriv console cron cron2 daemon ftp kern
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> local0 local1 local2 local3 local4 local5 local6 local7 lpr mail
|
||||
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> news ntp syslog user uucp
|
||||
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list all severity
|
||||
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> alert all critical debug emergency error info none notice warning
|
||||
<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list all severity critical
|
||||
<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list mail severity warning
|
||||
<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> leave
|
||||
<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>admin@example:/>
|
||||
</code></pre></div>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> the <code>log-file</code> syntax requires the leading prefix <code>file:</code>.
|
||||
If the path is not absolute, e.g., <code>file:mylog</code>, the file is saved to
|
||||
the system default path, i.e., <code>/log/mylog</code>. In this case, verify
|
||||
that the filename is not already in use.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>The <code>log-file</code> syntax requires the leading prefix <code>file:</code>. If the
|
||||
path is not absolute, e.g., <code>file:mylog</code>, the file is saved to the
|
||||
system default path, i.e., <code>/log/mylog</code>. In this case, verify that
|
||||
the filename is not already in use.</p>
|
||||
</div>
|
||||
<h2 id="log-rotation">Log Rotation<a class="headerlink" href="#log-rotation" title="Permanent link">¶</a></h2>
|
||||
<p>By default log files are allowed to grow to a size of 1 MiB after which
|
||||
they are "rotated". The whole reason for this is to not fill up the
|
||||
disk with outdated logs. A rotated file is saved in stages and older
|
||||
ones are also compressed (using <code>gzip</code>). Use the <code>show log</code> command in
|
||||
admin-exec context to start the log file viewer:</p>
|
||||
<div class="highlight"><pre><span></span><code>admin@example:/config/syslog/> do show log
|
||||
log log.0 log.1.gz log.2.gz log.3.gz log.4.gz log.5.gz
|
||||
admin@example:/config/syslog/> do show log log.1.gz
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>admin@example:/config/syslog/> do show log
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>log log.0 log.1.gz log.2.gz log.3.gz log.4.gz log.5.gz
|
||||
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>admin@example:/config/syslog/> do show log log.1.gz
|
||||
</code></pre></div>
|
||||
<blockquote>
|
||||
<p><strong>Tip:</strong> use the Tab key on your keyboard list available log files.
|
||||
The <code>do</code> prefix is also very useful in configure context to access
|
||||
commands from admin-exec context.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>Use the Tab key on your keyboard list available log files. The <code>do</code>
|
||||
prefix is also very useful in configure context to access commands
|
||||
from admin-exec context.</p>
|
||||
</div>
|
||||
<p>By default 10 compressed older files are saved. Here the oldest is
|
||||
<code>log.5.gz</code> and the most recently rotated one is <code>log.0</code>.</p>
|
||||
<p>Log file rotation can be configured both globally and per log file.
|
||||
Here we show the global settings, the set up is the same for per log
|
||||
file, which if unset inherit the global settings:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>admin@example:/><span class="w"> </span>configure<span class="w"> </span>
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>file-rotation
|
||||
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span>show
|
||||
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>admin@example:/config/syslog/file-rotation/>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>admin@example:/> configure
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>admin@example:/config/> edit syslog file-rotation
|
||||
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>admin@example:/config/syslog/file-rotation/> show
|
||||
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>admin@example:/config/syslog/file-rotation/>
|
||||
</code></pre></div>
|
||||
<p>The defaults are not shown. We can inspect them by asking the YANG
|
||||
model for the help texts:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">help</span>
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span>max-file-size<span class="w"> </span>number-of-files
|
||||
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">help</span><span class="w"> </span>max-file-size<span class="w"> </span>
|
||||
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>NAME
|
||||
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span>max-file-size<span class="w"> </span>kilobytes
|
||||
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>
|
||||
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a>DESCRIPTION
|
||||
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span>Maximum<span class="w"> </span>log<span class="w"> </span>file<span class="w"> </span>size<span class="w"> </span><span class="o">(</span>kiB<span class="o">)</span>,<span class="w"> </span>before<span class="w"> </span>rotation.
|
||||
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a>
|
||||
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a>DEFAULT
|
||||
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="w"> </span><span class="m">1024</span>
|
||||
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">help</span><span class="w"> </span>number-of-files<span class="w"> </span>
|
||||
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a>NAME
|
||||
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a><span class="w"> </span>number-of-files<span class="w"> </span><span class="o">[</span><span class="m">0</span>..4294967295<span class="o">]</span>
|
||||
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a>
|
||||
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a>DESCRIPTION
|
||||
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a><span class="w"> </span>Maximum<span class="w"> </span>number<span class="w"> </span>of<span class="w"> </span>log<span class="w"> </span>files<span class="w"> </span>retained.
|
||||
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a>
|
||||
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a>DEFAULT
|
||||
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a><span class="w"> </span><span class="m">10</span>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>admin@example:/config/syslog/file-rotation/> help
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a> max-file-size number-of-files
|
||||
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>admin@example:/config/syslog/file-rotation/> help max-file-size
|
||||
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>NAME
|
||||
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a> max-file-size kilobytes
|
||||
<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>
|
||||
<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>DESCRIPTION
|
||||
<a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a> Maximum log file size (kiB), before rotation.
|
||||
<a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a>
|
||||
<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a>DEFAULT
|
||||
<a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a> 1024
|
||||
<a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a>admin@example:/config/syslog/file-rotation/> help number-of-files
|
||||
<a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a>NAME
|
||||
<a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a> number-of-files [0..4294967295]
|
||||
<a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a>
|
||||
<a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a>DESCRIPTION
|
||||
<a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a> Maximum number of log files retained.
|
||||
<a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a>
|
||||
<a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a>DEFAULT
|
||||
<a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a> 10
|
||||
</code></pre></div>
|
||||
<p>To change the defaults to something smaller, 512 kiB and 20 (remember
|
||||
everything after .0 is compressed, and text compresses well):</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>max-file-size<span class="w"> </span><span class="m">512</span>
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>number-of-files<span class="w"> </span><span class="m">20</span>
|
||||
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span>show
|
||||
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>number-of-files<span class="w"> </span><span class="m">20</span><span class="p">;</span>
|
||||
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>max-file-size<span class="w"> </span><span class="m">512</span><span class="p">;</span>
|
||||
<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span>leave
|
||||
<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>admin@example:/><span class="w"> </span>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>max-file-size<span class="w"> </span><span class="m">512</span>
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>number-of-files<span class="w"> </span><span class="m">20</span>
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span>show
|
||||
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>number-of-files<span class="w"> </span><span class="m">20</span><span class="p">;</span>
|
||||
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>max-file-size<span class="w"> </span><span class="m">512</span><span class="p">;</span>
|
||||
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a>admin@example:/config/syslog/file-rotation/><span class="w"> </span>leave
|
||||
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>admin@example:/>
|
||||
</code></pre></div>
|
||||
<h2 id="log-format">Log Format<a class="headerlink" href="#log-format" title="Permanent link">¶</a></h2>
|
||||
<p>There are three major syslog log formats, the default is <a href="https://datatracker.ietf.org/doc/html/rfc3164">RFC3164</a> for
|
||||
@@ -1743,21 +1746,21 @@ log files and BSD for remote logging. Depending on time synchronization
|
||||
and remote log server capabilities, or policies, the <a href="https://datatracker.ietf.org/doc/html/rfc5424">RFC5424</a> format
|
||||
is often preferred since it not only has better time resolution but also
|
||||
supports structured logging:</p>
|
||||
<div class="highlight"><pre><span></span><code>BSD : myproc[8710]: Kilroy was here.
|
||||
RFC3164 : Aug 24 05:14:15 192.0.2.1 myproc[8710]: Kilroy was here.
|
||||
RFC5424 : 2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - Kilroy was here.
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>BSD : myproc[8710]: Kilroy was here.
|
||||
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>RFC3164 : Aug 24 05:14:15 192.0.2.1 myproc[8710]: Kilroy was here.
|
||||
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>RFC5424 : 2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - Kilroy was here.
|
||||
</code></pre></div>
|
||||
<p>The BSD format is only applicable to remote logging. It remains the
|
||||
default for compatibility reasons, and is recommended since the device
|
||||
may not have proper time, making it better for the remote log server to
|
||||
perform time stamping at the time of arrival.</p>
|
||||
<p>Configuring the log format is the same for log files and remotes:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>actions<span class="w"> </span>log-file<span class="w"> </span>file:foobar<span class="w"> </span>
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>admin@example:/config/syslog/actions/log-file/file:foobar/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>log-format<span class="w"> </span>
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span>bsd<span class="w"> </span>rfc3164<span class="w"> </span>rfc5424
|
||||
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>admin@example:/config/syslog/actions/log-file/file:foobar/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>log-format<span class="w"> </span>rfc5424<span class="w"> </span>
|
||||
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>admin@example:/config/syslog/actions/log-file/file:foobar/><span class="w"> </span>leave
|
||||
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a>admin@example:/>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>admin@example:/config/> edit syslog actions log-file file:foobar
|
||||
<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format
|
||||
<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a> bsd rfc3164 rfc5424
|
||||
<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format rfc5424
|
||||
<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>admin@example:/config/syslog/actions/log-file/file:foobar/> leave
|
||||
<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a>admin@example:/>
|
||||
</code></pre></div>
|
||||
<h2 id="log-to-remote-server">Log to Remote Server<a class="headerlink" href="#log-to-remote-server" title="Permanent link">¶</a></h2>
|
||||
<p>Logging to a remote syslog server is the recommended way of supervising
|
||||
@@ -1770,31 +1773,32 @@ because your device may not have DNS set up or even available, and some
|
||||
remote syslog servers do not support receiving time stamped log messages
|
||||
-- this is of course entirely dependent on how the remote server is set
|
||||
up, as well as local policy.</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog
|
||||
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span>actions<span class="w"> </span>file-rotation<span class="w"> </span>server
|
||||
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>actions<span class="w"> </span>destination<span class="w"> </span>moon
|
||||
<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span>
|
||||
<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w"> </span>facility-list<span class="w"> </span>log-format<span class="w"> </span>udp
|
||||
<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>udp
|
||||
<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w"> </span>address<span class="w"> </span>port
|
||||
<a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>udp<span class="w"> </span>address<span class="w"> </span><span class="m">192</span>.168.0.12
|
||||
<a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list<span class="w"> </span>container<span class="w"> </span>severity<span class="w"> </span>all
|
||||
<a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span>leave
|
||||
<a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a>admin@example:/>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog
|
||||
<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w"> </span>actions<span class="w"> </span>file-rotation<span class="w"> </span>server
|
||||
<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>actions<span class="w"> </span>destination<span class="w"> </span>moon
|
||||
<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span>
|
||||
<a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a><span class="w"> </span>facility-list<span class="w"> </span>log-format<span class="w"> </span>udp
|
||||
<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>udp
|
||||
<a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a><span class="w"> </span>address<span class="w"> </span>port
|
||||
<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>udp<span class="w"> </span>address<span class="w"> </span><span class="m">192</span>.168.0.12
|
||||
<a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>facility-list<span class="w"> </span>container<span class="w"> </span>severity<span class="w"> </span>all
|
||||
<a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a>admin@example:/config/syslog/actions/destination/moon/><span class="w"> </span>leave
|
||||
<a id="__codelineno-7-11" name="__codelineno-7-11" href="#__codelineno-7-11"></a>admin@example:/>
|
||||
</code></pre></div>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> the alternatives shown below each prompt in the example
|
||||
above can be found by tapping the Tab key.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>The alternatives shown below each prompt in the example above can be
|
||||
found by tapping the Tab key.</p>
|
||||
</div>
|
||||
<h2 id="acting-as-a-log-server">Acting as a Log Server<a class="headerlink" href="#acting-as-a-log-server" title="Permanent link">¶</a></h2>
|
||||
<p>The syslog server can act as a log sink for other devices on a LAN. For
|
||||
this to work you need a static IP address, here we use 10.0.0.1/24.</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>admin@example:/><span class="w"> </span>configure
|
||||
<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>server
|
||||
<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>admin@example:/config/syslog/server/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>enabled<span class="w"> </span><span class="nb">true</span>
|
||||
<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>admin@example:/config/syslog/server/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>listen<span class="w"> </span>udp<span class="w"> </span><span class="m">514</span><span class="w"> </span>address<span class="w"> </span><span class="m">10</span>.0.0.1
|
||||
<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>admin@example:/config/syslog/server/><span class="w"> </span>leave
|
||||
<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a>admin@example:/>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>admin@example:/><span class="w"> </span>configure
|
||||
<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>admin@example:/config/><span class="w"> </span>edit<span class="w"> </span>syslog<span class="w"> </span>server
|
||||
<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a>admin@example:/config/syslog/server/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>enabled<span class="w"> </span><span class="nb">true</span>
|
||||
<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a>admin@example:/config/syslog/server/><span class="w"> </span><span class="nb">set</span><span class="w"> </span>listen<span class="w"> </span>udp<span class="w"> </span><span class="m">514</span><span class="w"> </span>address<span class="w"> </span><span class="m">10</span>.0.0.1
|
||||
<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a>admin@example:/config/syslog/server/><span class="w"> </span>leave
|
||||
<a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a>admin@example:/>
|
||||
</code></pre></div>
|
||||
<p>See the above <a href="#log-to-file">Log to File</a> section on how to set up
|
||||
filtering of received logs to local files. Please note, filtering based
|
||||
|
||||
+141
-129
@@ -1800,31 +1800,36 @@
|
||||
|
||||
<h1 id="regression-testing-with-infamy">Regression Testing with Infamy<a class="headerlink" href="#regression-testing-with-infamy" title="Permanent link">¶</a></h1>
|
||||
<p>Infix comes with a test suite that is intended to provide end-to-end
|
||||
verification of supported features. Generally speaking, this means
|
||||
that one or more DUTs are configured over NETCONF; the resulting
|
||||
verification of supported features. Generally speaking, this means that
|
||||
one or more DUTs are configured over NETCONF or RESTCONF; the resulting
|
||||
network is then black-box tested by injecting and inspecting network
|
||||
traffic at various points.</p>
|
||||
<p>This document is intended to be a practical guide on how to run,
|
||||
develop and debug tests. There is a separate document describing the
|
||||
<a href="../test-arch/">Test System Architecture</a>.</p>
|
||||
<p>This document is intended to be a practical guide on how to run, develop
|
||||
and debug tests. There is a separate document describing the <a href="../test-arch/">Test
|
||||
System Architecture</a>.</p>
|
||||
<h2 id="modes-of-testing">Modes of Testing<a class="headerlink" href="#modes-of-testing" title="Permanent link">¶</a></h2>
|
||||
<h3 id="virtual-devices">Virtual Devices<a class="headerlink" href="#virtual-devices" title="Permanent link">¶</a></h3>
|
||||
<p>By default, tests are run on a topology made up of virtual Infix nodes
|
||||
using <a href="https://github.com/wkz/qeneth">Qeneth</a>. To run the full regression test suite: build Infix
|
||||
for <code>x86_64</code>:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make x86_64_defconfig
|
||||
$ make
|
||||
$ make test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>$ make x86_64_defconfig
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>...
|
||||
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>$ make
|
||||
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>...
|
||||
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>$ make test
|
||||
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>...
|
||||
</code></pre></div>
|
||||
<h3 id="physical-devices">Physical Devices<a class="headerlink" href="#physical-devices" title="Permanent link">¶</a></h3>
|
||||
<p>To run the tests on a preexisting topology from the host's network
|
||||
namespace, specify the <code>host</code> <code>TEST_MODE</code>:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make TEST_MODE=host test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>$ make TEST_MODE=host test
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>This typically used when testing on physical hardware. By default the
|
||||
topology will be sourced from <code>/etc/infamy.dot</code>, but this can be
|
||||
overwritten by setting the <code>TOPOLOGY</code> variable:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make TEST_MODE=host TOPOLOGY=~/my-topology.dot test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>$ make TEST_MODE=host TOPOLOGY=~/my-topology.dot test
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>...
|
||||
</code></pre></div>
|
||||
<h3 id="make-run-devices"><code>make run</code> Devices<a class="headerlink" href="#make-run-devices" title="Permanent link">¶</a></h3>
|
||||
<p>Some tests only require a single DUT. These can therefore be run
|
||||
@@ -1832,22 +1837,23 @@ against an Infix image started from <code>make run</code>. This requires that th
|
||||
instance is configured to use TAP networking.</p>
|
||||
<p>When the instance is running, you can open a separate terminal and run
|
||||
the subset of the test suite that can be mapped to it:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make TEST_MODE=run test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>$ make TEST_MODE=run test
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>...
|
||||
</code></pre></div>
|
||||
<h2 id="interactive-usage">Interactive Usage<a class="headerlink" href="#interactive-usage" title="Permanent link">¶</a></h2>
|
||||
<p>When developing and debugging tests, the overhead of repeatedly
|
||||
setting up and tearing down the test environment can quickly start to
|
||||
weigh you down. In these situation, you can start an interactive test
|
||||
environment:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make test-sh
|
||||
Info: Generating topology
|
||||
Info: Generating node YAML
|
||||
Info: Generating executables
|
||||
Info: Launching dut1
|
||||
Info: Launching dut2
|
||||
Info: Launching dut3
|
||||
Info: Launching dut4
|
||||
11:42:52 infamy0:test #
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>$ make test-sh
|
||||
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>Info: Generating topology
|
||||
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a>Info: Generating node YAML
|
||||
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>Info: Generating executables
|
||||
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>Info: Launching dut1
|
||||
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a>Info: Launching dut2
|
||||
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>Info: Launching dut3
|
||||
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a>Info: Launching dut4
|
||||
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a>11:42:52 infamy0:test #
|
||||
</code></pre></div>
|
||||
<p>The example above uses the default mode (<code>qeneth</code>), but the <code>host</code> and
|
||||
<code>run</code> modes also support the <code>test-sh</code> target.</p>
|
||||
@@ -1858,73 +1864,76 @@ devices, and <em>step</em> your code.</p>
|
||||
<h3 id="running-subsets-of-tests">Running Subsets of Tests<a class="headerlink" href="#running-subsets-of-tests" title="Permanent link">¶</a></h3>
|
||||
<p>Each test case is a separate executable, which can be run without
|
||||
arguments:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:42:53 infamy0:test # ./case/infix_dhcp/dhcp_basic.py
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>11:42:53 infamy0:test # ./case/infix_dhcp/dhcp_basic.py
|
||||
</code></pre></div>
|
||||
<p>To run a suite of tests, e.g., only the DHCP client tests, pass the
|
||||
suite as an argument to <a href="https://github.com/rical/9pm">9PM</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:42:53 infamy0:test # ./9pm/9pm.py case/infix_dhcp/infix_dhcp.yaml
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>11:42:53 infamy0:test # ./9pm/9pm.py case/infix_dhcp/infix_dhcp.yaml
|
||||
</code></pre></div>
|
||||
<p>To run the suite of all tests:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:42:53 infamy0:test # ./9pm/9pm.py case/all.yaml
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>11:42:53 infamy0:test # ./9pm/9pm.py case/all.yaml
|
||||
</code></pre></div>
|
||||
<h3 id="connecting-to-infamy">Connecting to Infamy<a class="headerlink" href="#connecting-to-infamy" title="Permanent link">¶</a></h3>
|
||||
<p>The test system runs in a Docker container, so to get a shell prompt in
|
||||
<em>another terminal</em> you need to connect to that container. Infamy comes
|
||||
with a helper script for this:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/shell
|
||||
11:42:53 infamy0:test #
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>$ ./test/shell
|
||||
<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>11:42:53 infamy0:test #
|
||||
</code></pre></div>
|
||||
<p>By default it connect to the latest started Infamy instance. If you for
|
||||
some reason run multiple instances of Infamy the <code>shell</code> script takes an
|
||||
optional argument "system", which is the hostname of the container you
|
||||
want to connect to:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/shell infamy2
|
||||
11:42:53 infamy2:test #
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>$ ./test/shell infamy2
|
||||
<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>11:42:53 infamy2:test #
|
||||
</code></pre></div>
|
||||
<h3 id="connecting-to-a-dut">Connecting to a DUT<a class="headerlink" href="#connecting-to-a-dut" title="Permanent link">¶</a></h3>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>The <code>console</code> script uses <code>telnet</code> to connect to a port forwarded to
|
||||
<code>localhost</code> by the Docker container. To exit Telnet, use Ctrl-] and
|
||||
then 'q' followed by enter. This can be customized in <code>~/.telnetrc</code></p>
|
||||
</div>
|
||||
<p>All DUTs in a virtual Infamy topology are emulated in Qemu instances
|
||||
managed by qeneth. If you want to watch what's happening on one of the
|
||||
target systems, e.g., tail a log file or run <code>tcpdump</code> during the test,
|
||||
there is another helper script in Infamy for this:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/console 1
|
||||
Trying 127.0.0.1...
|
||||
Connected to 127.0.0.1.
|
||||
|
||||
Infix OS — Immutable.Friendly.Secure v23.11.0-226-g0c144da (console)
|
||||
infix-00-00-00 login: admin
|
||||
Password:
|
||||
.-------.
|
||||
| . . | Infix OS — Immutable.Friendly.Secure
|
||||
|-. v .-| https://kernelkit.org
|
||||
'-'---'-'
|
||||
|
||||
Run the command 'cli' for interactive OAM
|
||||
|
||||
admin@infix-00-00-00:~$
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a>$ ./test/console 1
|
||||
<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>Trying 127.0.0.1...
|
||||
<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a>Connected to 127.0.0.1.
|
||||
<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a>
|
||||
<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a>Infix OS — Immutable.Friendly.Secure v23.11.0-226-g0c144da (console)
|
||||
<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a>infix-00-00-00 login: admin
|
||||
<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a>Password:
|
||||
<a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a>.-------.
|
||||
<a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a>| . . | Infix OS — Immutable.Friendly.Secure
|
||||
<a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a>|-. v .-| https://kernelkit.org
|
||||
<a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></a>'-'---'-'
|
||||
<a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a>
|
||||
<a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a>Run the command 'cli' for interactive OAM
|
||||
<a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a>
|
||||
<a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a>admin@infix-00-00-00:~$
|
||||
</code></pre></div>
|
||||
<p>From here we can observe <code>dut1</code> freely while running tests.</p>
|
||||
<blockquote>
|
||||
<p>The <code>console</code> script uses <code>telnet</code> to connect to a port forwarded to
|
||||
<code>localhost</code> by the Docker container. To exit Telnet, use Ctrl-] and
|
||||
then 'q' followed by enter. This can be customized in <code>~/.telnetrc</code></p>
|
||||
</blockquote>
|
||||
<p>Like the <code>shell</code> script, <code>console</code> takes an optional "system" argument
|
||||
in case you run multiple instances of Infamy:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/console 1 infamy2
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a>$ ./test/console 1 infamy2
|
||||
<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>You can also connect to the console of a DUT from within a <code>shell</code>:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/shell
|
||||
11:42:54 infamy0:test # qeneth status
|
||||
11:42:54 infamy0:test # qeneth console dut1
|
||||
login: admin
|
||||
password: *****
|
||||
admin@infix-00-00-00:~$
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>$ ./test/shell
|
||||
<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a>11:42:54 infamy0:test # qeneth status
|
||||
<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a>11:42:54 infamy0:test # qeneth console dut1
|
||||
<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a>login: admin
|
||||
<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a>password: *****
|
||||
<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a>admin@infix-00-00-00:~$
|
||||
</code></pre></div>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> disconnect from the qeneth console by using bringing up the
|
||||
old Telnet "menu" using Ctrl-], compared to standard Telnet this is
|
||||
the BusyBox version so you press 'e' + enter instead of 'q' to quit.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>Disconnect from the qeneth console by using bringing up the old Telnet
|
||||
"menu" using Ctrl-], compared to standard Telnet this is the BusyBox
|
||||
version so you press 'e' + enter instead of 'q' to quit.</p>
|
||||
</div>
|
||||
<h3 id="attaching-to-macvlans">Attaching to MACVLANs<a class="headerlink" href="#attaching-to-macvlans" title="Permanent link">¶</a></h3>
|
||||
<p>To fully isolate the host's interfaces from one another, many tests
|
||||
will stack a MACVLAN on an interface, which is then placed in a
|
||||
@@ -1932,20 +1941,20 @@ separate network namespace.</p>
|
||||
<p>It is often useful to attach to those namespaces, so that you can
|
||||
interactively inject traffic into the test setup.</p>
|
||||
<p>First, connect to the Infamy instance in question:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ ./test/shell
|
||||
11:43:19 infamy0:test #
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>$ ./test/shell
|
||||
<a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>11:43:19 infamy0:test #
|
||||
</code></pre></div>
|
||||
<p>Then, attach to the MACVLAN namespace by running the <code>nsenter</code> helper
|
||||
script from the test directory, supplying the base interface name as
|
||||
the first argument:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:43:19 infamy0:test # ./nsenter d1b
|
||||
11:43:20 infamy0(d1b):test #
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>11:43:19 infamy0:test # ./nsenter d1b
|
||||
<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>11:43:20 infamy0(d1b):test #
|
||||
</code></pre></div>
|
||||
<p>By default, an interactive shell is started, but you can also supply
|
||||
another command:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:43:19 infamy0:test # ./nsenter d1b ip -br addr
|
||||
lo UNKNOWN 127.0.0.1/8 ::1/128
|
||||
iface@if7 UP 10.0.0.1/24 fe80::38d0:88ff:fe77:b7cd/64
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>11:43:19 infamy0:test # ./nsenter d1b ip -br addr
|
||||
<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>lo UNKNOWN 127.0.0.1/8 ::1/128
|
||||
<a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a>iface@if7 UP 10.0.0.1/24 fe80::38d0:88ff:fe77:b7cd/64
|
||||
</code></pre></div>
|
||||
<p>You can now freely debug the network activity of your test and the
|
||||
responses from the DUT.</p>
|
||||
@@ -1956,13 +1965,13 @@ interactively inspect either the test's or the device's state.</p>
|
||||
<p>Simply insert a call to <code>breakpoint()</code> at the point of interest in
|
||||
your test and run it as normal. Once Python executes the call, it will
|
||||
drop you into the Python debugger:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:42:58 infamy0:test # ./case/infix_dhcp/dhcp_basic.py
|
||||
# Starting (2024-02-10 11:42:59)
|
||||
# Probing dut1 on port d1a for IPv6LL mgmt address ...
|
||||
# Connecting to mgmt IP fe80::ff:fe00:0%d1a:830 ...
|
||||
ok 1 - Initialize
|
||||
> /home/jocke/src/infix/test/case/infix_dhcp/dhcp_basic.py(44)<module>()
|
||||
(Pdb)
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>11:42:58 infamy0:test # ./case/infix_dhcp/dhcp_basic.py
|
||||
<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a># Starting (2024-02-10 11:42:59)
|
||||
<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a># Probing dut1 on port d1a for IPv6LL mgmt address ...
|
||||
<a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a># Connecting to mgmt IP fe80::ff:fe00:0%d1a:830 ...
|
||||
<a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a>ok 1 - Initialize
|
||||
<a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>> /home/jocke/src/infix/test/case/infix_dhcp/dhcp_basic.py(44)<module>()
|
||||
<a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a>(Pdb)
|
||||
</code></pre></div>
|
||||
<p>At this point you have full access to the test's state, but it is also
|
||||
an opportunity to inspect the state of the DUTs (e.g. via their
|
||||
@@ -1970,7 +1979,7 @@ console or over SSH).</p>
|
||||
<p>It is also possible to run a test under Pdb from the get-go, if you
|
||||
want to setup breakpoints without modifying the source, or simply step
|
||||
through the code:</p>
|
||||
<div class="highlight"><pre><span></span><code>11:42:58 infamy0:test # python -m pdb case/infix_dhcp/dhcp_basic.py
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>11:42:58 infamy0:test # python -m pdb case/infix_dhcp/dhcp_basic.py
|
||||
</code></pre></div>
|
||||
<h3 id="deterministic-topology-mappings">Deterministic Topology Mappings<a class="headerlink" href="#deterministic-topology-mappings" title="Permanent link">¶</a></h3>
|
||||
<p>By default, mappings from logical to physical topologies are not
|
||||
@@ -1979,43 +1988,43 @@ debugging a failing test, since logical nodes are suffled around
|
||||
between phyical nodes. In such cases, supplying a <code>PYTHONHASHSEED</code>
|
||||
variable (set to any 32-bit unsigned integer) when launching the test
|
||||
environment will make sure that topology mappings are deterministic:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make PYTHONHASHSEED=0 test-sh
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a>$ make PYTHONHASHSEED=0 test-sh
|
||||
</code></pre></div>
|
||||
<p>If a seed is not supplied, a random value is chosen. This seed is
|
||||
logged by the <code>meta/reproducible.py</code> test case when running a test
|
||||
suite:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make test
|
||||
Info: Generating topology
|
||||
Info: Generating node YAML
|
||||
Info: Generating executables
|
||||
Info: Launching dut1
|
||||
Info: Launching dut2
|
||||
Info: Launching dut3
|
||||
Info: Launching dut4
|
||||
9PM - Simplicity is the ultimate sophistication
|
||||
|
||||
Starting test 0002-reproducible.py
|
||||
2024-05-03 10:40:30 # Starting (2024-05-03 10:40:30)
|
||||
2024-05-03 10:40:30 # Specify PYTHONHASHSEED=3773822171 to reproduce this test environment
|
||||
2024-05-03 10:40:30 ok 1 - $PYTHONHASHSEED is set
|
||||
2024-05-03 10:40:30 # Exiting (2024-05-03 10:40:30)
|
||||
2024-05-03 10:40:30 1..1
|
||||
...
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a>$ make test
|
||||
<a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a>Info: Generating topology
|
||||
<a id="__codelineno-19-3" name="__codelineno-19-3" href="#__codelineno-19-3"></a>Info: Generating node YAML
|
||||
<a id="__codelineno-19-4" name="__codelineno-19-4" href="#__codelineno-19-4"></a>Info: Generating executables
|
||||
<a id="__codelineno-19-5" name="__codelineno-19-5" href="#__codelineno-19-5"></a>Info: Launching dut1
|
||||
<a id="__codelineno-19-6" name="__codelineno-19-6" href="#__codelineno-19-6"></a>Info: Launching dut2
|
||||
<a id="__codelineno-19-7" name="__codelineno-19-7" href="#__codelineno-19-7"></a>Info: Launching dut3
|
||||
<a id="__codelineno-19-8" name="__codelineno-19-8" href="#__codelineno-19-8"></a>Info: Launching dut4
|
||||
<a id="__codelineno-19-9" name="__codelineno-19-9" href="#__codelineno-19-9"></a>9PM - Simplicity is the ultimate sophistication
|
||||
<a id="__codelineno-19-10" name="__codelineno-19-10" href="#__codelineno-19-10"></a>
|
||||
<a id="__codelineno-19-11" name="__codelineno-19-11" href="#__codelineno-19-11"></a>Starting test 0002-reproducible.py
|
||||
<a id="__codelineno-19-12" name="__codelineno-19-12" href="#__codelineno-19-12"></a>2024-05-03 10:40:30 # Starting (2024-05-03 10:40:30)
|
||||
<a id="__codelineno-19-13" name="__codelineno-19-13" href="#__codelineno-19-13"></a>2024-05-03 10:40:30 # Specify PYTHONHASHSEED=3773822171 to reproduce this test environment
|
||||
<a id="__codelineno-19-14" name="__codelineno-19-14" href="#__codelineno-19-14"></a>2024-05-03 10:40:30 ok 1 - $PYTHONHASHSEED is set
|
||||
<a id="__codelineno-19-15" name="__codelineno-19-15" href="#__codelineno-19-15"></a>2024-05-03 10:40:30 # Exiting (2024-05-03 10:40:30)
|
||||
<a id="__codelineno-19-16" name="__codelineno-19-16" href="#__codelineno-19-16"></a>2024-05-03 10:40:30 1..1
|
||||
<a id="__codelineno-19-17" name="__codelineno-19-17" href="#__codelineno-19-17"></a>...
|
||||
</code></pre></div>
|
||||
<p>This is useful because this value can then be used to rerun a test (or
|
||||
the whole suite) with identical topology mappings:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make PYTHONHASHSEED=3773822171 TESTS=case/ietf_system/hostname.py test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a>$ make PYTHONHASHSEED=3773822171 TESTS=case/ietf_system/hostname.py test
|
||||
</code></pre></div>
|
||||
<h3 id="deterministic-transport-protocol">Deterministic Transport Protocol<a class="headerlink" href="#deterministic-transport-protocol" title="Permanent link">¶</a></h3>
|
||||
<p>By default, the communication transport protocol (NETCONF/RESTCONF) is
|
||||
chosen randomly. If you supply a <code>PYTHONHASHSEED</code> as described above,
|
||||
you get the same protocol used for that hash. But if you want to choose
|
||||
the protocol, add extra arguments to Infamy:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make INFAMY_EXTRA_ARGS="--transport=restconf" TESTS=case/ietf_system/hostname.py test
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a>$ make INFAMY_EXTRA_ARGS="--transport=restconf" TESTS=case/ietf_system/hostname.py test
|
||||
</code></pre></div>
|
||||
<p>or, when running interactively:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make test-sh
|
||||
09:08:17 infamy0:test # ./9pm/9pm.py -o"--transport=restconf" case/ietf_system/hostname.py
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a>$ make test-sh
|
||||
<a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a>09:08:17 infamy0:test # ./9pm/9pm.py -o"--transport=restconf" case/ietf_system/hostname.py
|
||||
</code></pre></div>
|
||||
<h3 id="test-specification">Test specification<a class="headerlink" href="#test-specification" title="Permanent link">¶</a></h3>
|
||||
<p>The test specification is automaticly generated from the test cases,
|
||||
@@ -2024,54 +2033,57 @@ this puts some constraints on the test cases:</p>
|
||||
only the steps so the result can be reproduced manually. E.g., instead
|
||||
of <code>set ip address on the interface</code> it should be more human readable,
|
||||
for example:</p>
|
||||
<p><div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">test</span><span class="o">.</span><span class="n">step</span><span class="p">(</span><span class="s2">"Set IPv4 address on the interface dut:cross"</span><span class="p">)</span>
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="n">test</span><span class="o">.</span><span class="n">step</span><span class="p">(</span><span class="s2">"Verify the IP address is set on dut:cross"</span><span class="p">)</span>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="n">test</span><span class="o">.</span><span class="n">step</span><span class="p">(</span><span class="s2">"Set IPv4 address on the interface dut:cross"</span><span class="p">)</span>
|
||||
<a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="n">test</span><span class="o">.</span><span class="n">step</span><span class="p">(</span><span class="s2">"Verify the IP address is set on dut:cross"</span><span class="p">)</span>
|
||||
</code></pre></div>
|
||||
where dut, cross and the IPv4 address could be found inside the
|
||||
<p>where <em>dut</em>, <em>cross</em> and the IPv4 address could be found inside the
|
||||
logical topology for the test.</p>
|
||||
<p>Each test case must begin with the test name followed by a empty line and
|
||||
the description of the test. For example:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>"""
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>Set hostname
|
||||
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
|
||||
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>Verify that it it possible to change hostname
|
||||
<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>"""
|
||||
<p>Each test case must begin with the test name followed by a empty line
|
||||
and the description of the test. For example:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a>"""
|
||||
<a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a>Set hostname
|
||||
<a id="__codelineno-24-3" name="__codelineno-24-3" href="#__codelineno-24-3"></a>
|
||||
<a id="__codelineno-24-4" name="__codelineno-24-4" href="#__codelineno-24-4"></a>Verify that it it possible to change hostname
|
||||
<a id="__codelineno-24-5" name="__codelineno-24-5" href="#__codelineno-24-5"></a>"""
|
||||
</code></pre></div>
|
||||
<p>The test specifaction can be genererated with:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ make test-spec
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a>$ make test-spec
|
||||
<a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a>...
|
||||
</code></pre></div>
|
||||
<h3 id="test-development">Test Development<a class="headerlink" href="#test-development" title="Permanent link">¶</a></h3>
|
||||
<p>For adding a new test to the automated regression test suite, it's best
|
||||
to start by reviewing an existing test case.</p>
|
||||
<p>All tests are located in the <code>infix/test/case</code> repository and are
|
||||
grouped by the features they verify. For example,
|
||||
<code>infix/test/case/infix_services</code> contains tests for various Infix
|
||||
<p>All tests are located in the <code>infix/test/case</code> repository and are
|
||||
grouped by the features they verify. For example,
|
||||
<code>infix/test/case/infix_services</code> contains tests for various Infix
|
||||
services, such as LLDP and mDNS.</p>
|
||||
<p>While test grouping is flexible, each test should be placed in a
|
||||
<p>While test grouping is flexible, each test should be placed in a
|
||||
logically relevant category.</p>
|
||||
<p>When creating a new test group, add it to <code>infix/test/case/all.yaml</code>,
|
||||
to enable it to run as a
|
||||
<a href="#running-subsets-of-tests">subset of the test suite</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>- name: infix-services
|
||||
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a> suite: infix_services/infix_services.yaml
|
||||
<p>When creating a new test group, add it to <code>infix/test/case/all.yaml</code>, to
|
||||
enable it to run as a <a href="#running-subsets-of-tests">subset of the test
|
||||
suite</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a>- name: infix-services
|
||||
<a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a> suite: infix_services/infix_services.yaml
|
||||
</code></pre></div>
|
||||
<p>A new test (e.g., lldp_enable_disable) should be added to the
|
||||
corresponding test group .yaml file, such as
|
||||
<p>A new test (e.g., lldp_enable_disable) should be added to the
|
||||
corresponding test group .yaml file, such as
|
||||
<code>infix/test/cases/infix_services.yaml</code>:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>- name: lldp_enable_disable
|
||||
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a> case: lldp_enable_disable/test.py
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-1"></a>- name: lldp_enable_disable
|
||||
<a id="__codelineno-27-2" name="__codelineno-27-2" href="#__codelineno-27-2"></a> case: lldp_enable_disable/test.py
|
||||
</code></pre></div>
|
||||
<p>It is necessary to include the test in
|
||||
<code>infix/test/case/infix_services/Readme.adoc</code> to ensure proper test
|
||||
<p>It is necessary to include the test in
|
||||
<code>infix/test/case/infix_services/Readme.adoc</code> to ensure proper test
|
||||
specification generation:</p>
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>include::lldp_enable_disable/Readme.adoc[]
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a>include::lldp_enable_disable/Readme.adoc[]
|
||||
</code></pre></div>
|
||||
<p>Each test case should have its own directory under,
|
||||
<code>infix/test/case/infix_services</code>, containing:
|
||||
- <code>test.py</code> - the test script
|
||||
- <code>topology.dot</code> - the logical topology definition.</p>
|
||||
<p>When the <a href="#test-specification">test specification</a> is generated,
|
||||
<code>topology.svg</code> and <code>Readme.adoc</code> should also be created. </p>
|
||||
<p>Each test case should have its own directory under,
|
||||
<code>infix/test/case/infix_services</code>, containing:</p>
|
||||
<ul>
|
||||
<li><code>test.py</code> - the test script</li>
|
||||
<li><code>topology.dot</code> - the logical topology definition.</li>
|
||||
</ul>
|
||||
<p>When the <a href="#test-specification">test specification</a> is generated,
|
||||
<code>topology.svg</code> and <code>Readme.adoc</code> should also be created.</p>
|
||||
|
||||
|
||||
|
||||
|
||||
+11
-8
@@ -1566,19 +1566,22 @@ there is an <code>x86_64</code> build that runs in <a href="https://www.qemu.org
|
||||
which is a very user-friendly tool for playing around with simple to
|
||||
complex network setups, verifying interoperability between vendors, etc.</p>
|
||||
<h2 id="qemu">QEMU<a class="headerlink" href="#qemu" title="Permanent link">¶</a></h2>
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong> installation for Debian/Ubuntu based systems: <kbd>sudo apt
|
||||
install virt-manager</kbd> -- dependencies ensure the relevant Qemu
|
||||
packages are pulled in as well. Installing <a href="https://virt-manager.org/">virt-manager</a> helps
|
||||
set up Qemu networking on your system.</p>
|
||||
</blockquote>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>Installation for Debian/Ubuntu based systems can be done by "simply":
|
||||
<kbd>sudo apt install virt-manager</kbd> -- dependencies ensure the
|
||||
relevant Qemu packages are pulled in as well. This trick, installing
|
||||
<a href="https://virt-manager.org/">virt-manager</a>, helps set up Qemu networking on your system.</p>
|
||||
</div>
|
||||
<p>A virtualized Infix x86_64 instance can easily be launched from a Linux
|
||||
system, with <a href="https://www.qemu.org/">Qemu</a> installed, by issuing:</p>
|
||||
<div class="highlight"><pre><span></span><code>./qemu.sh
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>$ ./qemu.sh
|
||||
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>from an unpacked <a href="https://github.com/kernelkit/infix/releases">release tarball</a>. From a built source tree of
|
||||
Infix the same functionality is bundled as:</p>
|
||||
<div class="highlight"><pre><span></span><code>make run
|
||||
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>$ make run
|
||||
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>...
|
||||
</code></pre></div>
|
||||
<p>To change settings, e.g. networking, <kbd>make run-menuconfig</kbd>, or
|
||||
from a pre-built Infix release tarball, using <kbd>./qemu.sh -c</kbd></p>
|
||||
|
||||
Reference in New Issue
Block a user