summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml')
-rw-r--r--doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml209
1 files changed, 0 insertions, 209 deletions
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
deleted file mode 100644
index 56bdda9..0000000
--- a/doc/book-enea-nfv-access-reference-guide-intel/doc/ostree.xml
+++ /dev/null
@@ -1,209 +0,0 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="ostree">
5 <title>Software Update</title>
6
7 <para>Enea's Software Update solution is based on OSTree.</para>
8 <para>OSTree is an upgrade system for Linux-based operating systems that
9 performs atomic upgrades of complete filesystem trees. The underlying
10 architecture might be summarized as "git for operating system binaries". It
11 operates in userspace, and will work on top of any Linux filesystem. At its
12 core is a git-like content-addressed object store with branches (or "refs")
13 to track meaningful filesystem trees within the store. Similarly, one can
14 check out or commit to these branches.</para>
15
16 <para>For in-depth information on how OSTree works, consult the OSTree User
17 Manual, <ulink
18 url="https://ostree.readthedocs.io/en/latest/manual/introduction">ostree.readthedocs</ulink>.
19 The set of OSTree commands can be found at the following OSTree <ulink
20 url="https://www.mankier.com/package/ostree">man page.</ulink></para>
21
22 <section id="installing_system_upgrades">
23 <title>Installing system upgrades</title>
24
25 <para>OSTree works by downloading system updates from remote servers,
26 which have to be set up before installing any system upgrades. There are
27 multiple ways through which system upgrades can be installed. Similarly to
28 git, one of the methods consists of pulling the branch related information
29 from the repository and checking out a commit ID. Another method, consists
30 of using a repository and a branch as the origin for future updates and
31 periodically pull the latest updates. Both of these techniques will be
32 detailed in the sections below.</para>
33
34 <section id="installing_by_commit_id">
35 <title>Installing a system upgrade by using a commit ID</title>
36
37 <para>To upgrade a system by using a commit ID, a remote repository has
38 to be added on the board running NFV Access:</para>
39
40 <para><emphasis role="bold">How to upgrade a system by using a commit
41 ID</emphasis></para>
42
43 <orderedlist>
44 <listitem>
45 <para>Add a remote repository on the board running NFV
46 Access:</para>
47
48 <programlisting>ostree remote add nfv-access-remote https://&lt;ostree-repository&gt;:&lt;port&gt;</programlisting>
49 </listitem>
50
51 <listitem>
52 <para>Pull the branch related information from the
53 repository:</para>
54
55 <programlisting>ostree pull nfv-access-remote &lt;branch-name&gt;</programlisting>
56 </listitem>
57
58 <listitem>
59
60 <para>Inspect the branch commits:</para>
61
62 <programlisting>ostree log &lt;branch-name&gt;</programlisting>
63
64 Inspecting the branch commits, outputs data in the following format:
65
66 <programlisting>commit &lt;COMMIT-ID&gt;
67ContentChecksum: &lt;CHECKSUM&gt;
68Date: &lt;COMMIT-DATE&gt;
69
70&lt;COMMIT-DESCRIPTION&gt;</programlisting>
71
72 <para>Example:</para>
73 <programlisting>ostree log nfv-access-latest
74commit 83e66d4376b415fca6a243ac4cf7704b8fceb0220621ff5aa59b4ee0715b9567
75ContentChecksum: dc5e7d46151acccae052751730e22062bd2d9ca6fa9990a622000e909e879467
76Date: 2018-12-20 16:04:22 +0000
77
78Commit example number 2
79
80commit 6e03344470b35385e584a79cd395ca90d134851b4cc512edeea5380f3cccc812
81ContentChecksum: 1d6a362491ecb25d5f56b9d6300463c0263bb68c8b50a368b1250c061225ba60
82Date: 2018-12-20 15:16:09 +0000
83
84Commit example number 1</programlisting>
85
86 </listitem>
87
88 <listitem>
89 <para>Specify the commit ID you wish to deploy</para>
90
91 <programlisting>ostree admin deploy &lt;COMMIT-ID&gt;</programlisting>
92 </listitem>
93 </orderedlist>
94
95 <note>
96 <para>Running <literal>ostree admin deploy</literal> will upgrade the
97 GRUB configuration to set the newly deployed commit as the default NFV
98 Access version.</para>
99 </note>
100 </section>
101
102 <section id="installing_by_update_channel">
103 <title>Installing a system upgrade by using an update channel</title>
104
105 <para>To upgrade a system by using an update channel, a remote
106 repository has to be configured as the origin for future updates:</para>
107
108 <programlisting>ostree admin set-origin nfv-access-remote \
109 https://&lt;ostree-repository&gt;:&lt;port&gt; &lt;branch-name&gt;</programlisting>
110
111 <para>Each time the remote branch is updated, the changes can be
112 deployed on a board with the <literal>ostree admin upgrade</literal>
113 command.</para>
114 </section>
115
116 <section id="removing_invalid_sys_upgrade">
117 <title>How to remove an invalid ostree version</title>
118
119 <orderedlist>
120 <listitem>
121 <para> Identify which commit is invalid by running <literal>ostree
122 admin status,</literal> which lists current commits. Example output:
123 </para>
124
125 <programlisting>ostree admin status
126 poky 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0.0 (pending)
127 origin refspec: 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0
128 * poky 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12.0
129 origin refspec: 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12
130 poky 8791932934bcfd33e2d3c0c9d2fbd63f90486cd62c5ddae40f8d2b94ba4a.0 (rollback)
131 origin refspec: my-remote:test-branch</programlisting>
132 </listitem>
133
134 <listitem>
135 <para>Undeploy the faulty commit by running <literal>ostree admin
136 undeploy &lt;commit number&gt;</literal>, where <literal>&lt;commit
137 number&gt;</literal>is the index of the commits listed in the
138 <literal>ostree admin status</literal> command.</para>
139
140 <programlisting>ostree undeploy 2</programlisting>
141 </listitem>
142
143 <listitem>
144 <para>Run the <literal>ostree admin status</literal> command to verify
145 the invalid version has been removed:</para>
146
147 <programlisting>ostree admin status
148 poky 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0.0 (pending)
149 origin refspec: 210f327ab52730c33910f9a40108333b353b36adfadf44a7d7579d3f57d0
150 * poky 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12.0
151 origin refspec: 884256bab349d7d4e1bfd603d70b59cae9143b4d7e996256246760815c12</programlisting>
152 </listitem>
153 </orderedlist>
154 </section>
155 </section>
156
157 <section id="change_builtin_kernel_param">
158 <title>Changing built-in kernel parameters</title>
159
160 <para>Each time OSTree deploys or undeploys a commit, the GRUB
161 configuration file is generated automatically. System administrators can
162 change what kernel parameters are specified in the GRUB configuration
163 file, by editing <literal>/etc/enea-nfv-access/boot/00_default</literal>
164 or creating a file in the same folder, for example
165 <literal>/etc/enea-nfv-access/boot/10_custom</literal>.</para>
166
167 <para>When a GRUB configuration file is created, files in the
168 <literal>/etc/enea-nfv-access/boot/</literal> folder are evaluated in
169 alphanumeric order, making, for example, a file named
170 <literal><literal>10_custom</literal></literal> override settings set in
171 <literal><literal>00_default</literal></literal>.</para>
172
173 <para><emphasis role="bold">There are 3 keywords that can change the way
174 GRUB configurations are created:</emphasis></para>
175
176 <itemizedlist>
177 <listitem>
178 <para><literal>base_folder</literal>: specifies where boot specific
179 files are located, such as kernel binaries, initrd files or GRUB
180 configurations.</para>
181 </listitem>
182
183 <listitem>
184 <para><literal>machine_config</literal>: specifies machine-specific
185 kernel parameters. For example this keyword should specify what serial
186 port is used for kernel boot messages or how to initialize network
187 connections.</para>
188 </listitem>
189
190 <listitem>
191 <para><literal>extra_config</literal>: specifies what other kernel
192 parameters should be added to the command line. This keyword should be
193 followed by kernel parameters that are not specific to the machine
194 (e.g. number of hugepages).</para>
195 </listitem>
196 </itemizedlist>
197
198 <para>A keyword should always be followed by a <literal>space</literal>
199 character and the content that is associated with that keyword:
200 <literal>&lt;keyword&gt; &lt;content&gt;</literal>.</para>
201
202 <para>If a change has been done in the
203 <literal>/etc/enea-nfv-access/boot</literal> folder, the GRUB
204 configuration can be explicitly regenerated by running <literal>
205 /usr/lib/ostree/ostree-grub-generator -o /boot/loader/grub.cfg
206 </literal> or waiting until the
207 next OSTree version is deployed.</para>
208 </section>
209</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-06-01 15:24:45 +0000