reference guide: add ostree section

Change-Id: Idde94a6bd36da0a17c501b7095f96945c8b48560
Signed-off-by: Sona Sarmadi <sona.sarmadi@enea.com>

2 files changed, 210 insertions, 0 deletions

diff --git a/doc/book-enea-nfv-access-reference-guide-intel/doc/book.xml b/doc/book-enea-nfv-access-reference-guide-intel/doc/book.xml
index e2819e1..ad26c6e 100644
--- a/doc/book-enea-nfv-access-reference-guide-intel/doc/book.xml
+++ b/doc/book-enea-nfv-access-reference-guide-intel/doc/book.xml
@@ -21,6 +21,8 @@
                 xmlns:xi="http://www.w3.org/2001/XInclude" />
         <xi:include href="dpdk.xml"
                 xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="ostree.xml"
+                xmlns:xi="http://www.w3.org/2001/XInclude" />
         <xi:include href="benchmarks.xml"
                 xmlns:xi="http://www.w3.org/2001/XInclude" />
         <xi:include href="using_nfv_access_sdks.xml"
diff --git a/doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml b/doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml
new file mode 100755
index 0000000..05d54e6
--- /dev/null
+++ b/doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml
@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="ostree">
+  <title>OSTree</title>
+
+  <para>OSTree is an upgrade system for Linux-based operating systems that
+  performs atomic upgrades of complete filesystem trees. The underlying
+  architecture might be summarized as "git for operating system binaries". It
+  operates in userspace, and will work on top of any Linux filesystem. At its
+  core is a git-like content-addressed object store with branches (or "refs")
+  to track meaningful filesystem trees within the store. Similarly, one can
+  check out or commit to these branches.</para>
+
+  <para>For in-depth information on how OSTree works, consult the OSTree User
+  Manual, <ulink
+  url="https://ostree.readthedocs.io/en/latest/manual/introduction">ostree.readthedocs</ulink>.
+  The set of OSTree commands can be found at the following OSTree <ulink
+  url="https://www.mankier.com/package/ostree">man page.</ulink></para>
+
+  <section id="installing_system_upgrades">
+    <title>Installing system upgrades</title>
+
+    <para>OSTree works by downloading system updates from remote servers,
+    which have to be set up before installing any system upgrades. There are
+    multiple ways through which system upgrades can be installed. Similarly to
+    git, one of the methods consists of pulling the branch related information
+    from the repository and checking out a commit ID. Another method, consists
+    of using a repository and a branch as the origin for future updates and
+    periodically pull the latest updates. Both of these techniques will be
+    detailed in the sections below.</para>
+
+    <section id="installing_by_commit_id">
+      <title>Installing a system upgrade by using a commit ID</title>
+
+      <para>To upgrade a system by using a commit ID, a remote repository has
+      to be added on the board running NFV Access:</para>
+
+      <para><emphasis role="bold">How to upgrade a system by using a commit
+      ID</emphasis></para>
+
+      <orderedlist>
+        <listitem>
+          <para>Add a remote repository on the board running NFV
+          Access:</para>
+
+          <programlisting>ostree remote add nfv-access-remote https://&lt;ostree-repository&gt;:&lt;port&gt;</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Pull the branch related information from the
+          repository:</para>
+
+          <programlisting>ostree pull nfv-access-remote &lt;branch-name&gt;</programlisting>
+        </listitem>
+
+        <listitem>
+
+          <para>Inspect the branch commits:</para>
+
+          <programlisting>ostree log &lt;branch-name&gt;</programlisting>
+
+           Inspecting the branch commits, outputs data in the following format: 
+
+          <programlisting>commit &lt;COMMIT-ID&gt;
+ContentChecksum: &lt;CHECKSUM&gt;
+Date: &lt;COMMIT-DATE&gt;
+
+&lt;COMMIT-DESCRIPTION&gt;
+
+Example:
+ostree log nfv-access-latest
+commit 83e66d4376b415fca6a243ac4cf7704b8fceb0220621ff5aa59b4ee0715b9567
+ContentChecksum: dc5e7d46151acccae052751730e22062bd2d9ca6fa9990a622000e909e879467
+Date: 2018-12-20 16:04:22 +0000
+
+Commit example number 2
+
+commit 6e03344470b35385e584a79cd395ca90d134851b4cc512edeea5380f3cccc812
+ContentChecksum: 1d6a362491ecb25d5f56b9d6300463c0263bb68c8b50a368b1250c061225ba60
+Date: 2018-12-20 15:16:09 +0000
+
+Commit example number 1</programlisting>
+
+           
+        </listitem>
+
+        <listitem>
+          <para>Specify the commit ID you wish to deploy</para>
+
+          <programlisting>ostree admin deploy &lt;COMMIT-ID&gt;</programlisting>
+        </listitem>
+      </orderedlist>
+
+      <note>
+        <para>Running <literal>ostree admin deploy</literal> will upgrade the
+        GRUB configuration to set the newly deployed commit as the default NFV
+        Access version.</para>
+      </note>
+    </section>
+
+    <section id="installing_by_update_channel">
+      <title>Installing a system upgrade by using an update channel</title>
+
+      <para>To upgrade a system by using an update channel, a remote
+      repository has to be configured as the origin for future updates:</para>
+
+      <programlisting>ostree admin set-origin nfv-access-remote \
+       https://&lt;ostree-repository&gt;:&lt;port&gt; &lt;branch-name&gt;</programlisting>
+
+      <para>Each time the remote branch is updated, the changes can be
+      deployed on a board with the <literal>ostree admin upgrade</literal>
+      command.</para>
+    </section>
+
+    <section id="removing_invalid_sys_upgrade">
+      <title>How to correctly remove an invalid ostree version</title>
+
+      <orderedlist>
+        <listitem>
+          <para> Identify which commit is invalid by running <literal>ostree
+          admin status,</literal> which lists current commits. Example output:
+          </para>
+
+          <programlisting>ostree admin status
+    poky 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0.0 (pending)
+       origin refspec: 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0
+    * poky 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12.0
+       origin refspec: 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12
+    poky 8791932934bcfd33e2d3c0c9d2fbd63f90486cd62c5ddae40f8d2b94ba4a.0 (rollback)
+       origin refspec: my-remote:test-branch</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Undeploy the faulty commit by running <literal>ostree admin
+          undeploy &lt;commit number&gt;</literal>, where <literal>&lt;commit
+          number&gt;</literal>is the index of the commits listed in the
+          <literal>ostree admin status</literal> command.</para>
+
+          <programlisting>ostree undeploy 2</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Run the <literal>ostree admin status</literal> command to verify
+          the invalid version has been removed:</para>
+
+          <programlisting>ostree admin status
+    poky 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0.0 (pending)
+       origin refspec: 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0
+    * poky 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12.0
+       origin refspec: 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12</programlisting>
+        </listitem>
+      </orderedlist>
+    </section>
+  </section>
+
+  <section id="change_builtin_kernel_param">
+    <title>Changing built-in kernel parameters</title>
+
+    <para>Each time OSTree deploys or undeploys a commit, the GRUB
+    configuration file is generated automatically. System administrators can
+    change what kernel parameters are specified in the GRUB configuration
+    file, by editing <literal>/etc/enea-nfv-access/boot/00_default</literal>
+    or creating a file in the same folder, for example
+    <literal>/etc/enea-nfv-access/boot/10_custom</literal>.</para>
+
+    <para>When a GRUB configuration file is created, files in the
+    <literal>/etc/enea-nfv-access/boot/</literal> folder are evaluated in
+    alphanumeric order, making, for example, a file named
+    <literal><literal>10_custom</literal></literal> override settings set in
+    <literal><literal>00_default</literal></literal>.</para>
+
+    <para><emphasis role="bold">There are 3 keywords that can change the way
+    GRUB configurations are created:</emphasis></para>
+
+    <itemizedlist>
+      <listitem>
+        <para><literal>base_folder</literal>: specifies where boot specific
+        files are located, such as kernel binaries, initrd files or GRUB
+        configurations.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>machine_config</literal>: specifies machine-specific
+        kernel parameters. For example this keyword should specify what serial
+        port is used for kernel boot messages or how to initialize network
+        connections.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>extra_config</literal>: specifies what other kernel
+        parameters should be added to the command line. This keyword should be
+        followed by kernel parameters that are not specific to the machine
+        (e.g. number of hugepages).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>A keyword should always be followed by a <literal>space</literal>
+    character and the content that is associated with that keyword:
+    <literal>&lt;keyword&gt; &lt;content&gt;</literal>.</para>
+
+    <para>If a change has been done in the
+    <literal>/etc/enea-nfv-access/boot</literal> folder, the GRUB
+    configuration can be explicitly regenerated by running <literal>
+    nfv-grub-generator -o /boot/loader/grub.cfg</literal> or waiting until the
+    next OSTree version is deployed.</para>
+  </section>
+</chapter>