summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/book-enea-nfv-access-guide/doc/getting_started.xml296
1 files changed, 1 insertions, 295 deletions
diff --git a/doc/book-enea-nfv-access-guide/doc/getting_started.xml b/doc/book-enea-nfv-access-guide/doc/getting_started.xml
index b6cf927..5972a90 100644
--- a/doc/book-enea-nfv-access-guide/doc/getting_started.xml
+++ b/doc/book-enea-nfv-access-guide/doc/getting_started.xml
@@ -1,4 +1,4 @@
1<?xml version="1.0" encoding="ISO-8859-1"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="plat-release-content"> 4<chapter id="plat-release-content">
@@ -42,300 +42,6 @@ Use dash as the default system shell (/bin/sh)? No</programlisting>
42 </itemizedlist> 42 </itemizedlist>
43 </section> 43 </section>
44 44
45 <section id="access_installer">
46 <title>Enea NFV Access Installer</title>
47
48 <para>The easiest way to get started with Enea NFV Access is by using the
49 installer provided for each supported architecture in this release. Each
50 installer guides you in the creation of a bootable Enea NFV Access
51 installation on a physical media.</para>
52
53 <section id="prereq">
54 <title>Prerequisites</title>
55
56 <para>The following files are needed on the development host
57 machine:</para>
58
59 <itemizedlist>
60 <listitem>
61 <para>A GRUB.efi binary - available from the <ulink url="???">GNU
62 GRUB download page</ulink>.</para>
63 </listitem>
64
65 <listitem>
66 <para>For booting from an SSD/HDD: a rootfs that needs to be
67 installed on the board (e.g.
68 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access/enea-nfv-access.tar.gz</filename>).</para>
69 </listitem>
70
71 <listitem>
72 <para>For USB booting: a development based rootfs (e.g.
73 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access-dev/enea-nfv-access-dev-inteld1521.tar.gz</filename>).</para>
74 </listitem>
75 </itemizedlist>
76
77 <para>Using the installer on the development host requires the
78 following:</para>
79
80 <itemizedlist>
81 <listitem>
82 <para>A physical drive of 16GB or larger</para>
83 </listitem>
84
85 <listitem>
86 <para>Root permissions</para>
87 </listitem>
88 </itemizedlist>
89 </section>
90
91 <section id="installer_setup_usage">
92 <title>Installer Setup and Usage</title>
93
94 <para><emphasis role="bold">To install Enea NFV Access on a physical
95 drive</emphasis></para>
96
97 <orderedlist>
98 <listitem>
99 <para>Go to the installer location: <programlisting># cd [path_to_EneaNFV_Access_folder]/[architecture]/install/
100nfv-installer/script-installer</programlisting></para>
101 </listitem>
102
103 <listitem>
104 <para>Execute the script file, this will bring you to the installer
105 prompt: <programlisting># sudo ./nfv_installer.sh</programlisting></para>
106 </listitem>
107
108 <listitem>
109 <para>Optionally, press ENTER to see the list of available
110 commands:<programlisting>help - displays a guide on how to use the installer
111list-params - lists all available parameters
112list-steps - lists the installer steps and the parameters that they depend on
113set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>)
114clear - clears a parameter (e.g. <literal>clear drive</literal>)
115list-partitions - lists current drives and partitions
116dry - performs a simulation test run
117run - executes the installer, using the values you set for each parameter
118q or quit - exits the script</programlisting></para>
119 </listitem>
120
121 <listitem>
122 <para>Set the required parameters depending on what steps you want
123 to run:</para>
124
125 <note>
126 <para>When using the installer for the first time, make sure to
127 set ALL parameters in order to be able to run all steps. See <xref
128 linkend="example_two">
129 "Example 2"
130 </xref> for details.</para>
131 </note>
132
133 <para><programlisting># set &lt;parameter_name&gt;=&lt;parameter_value&gt;</programlisting></para>
134
135 <orderedlist>
136 <listitem>
137 <para><parameter>drive=&lt;/dev/sdaX&gt;</parameter> - the drive
138 to partition</para>
139 </listitem>
140
141 <listitem>
142 <para><parameter>grub_binary=&lt;file&gt;</parameter> - points
143 to the <filename>GRUB</filename> executable to be installed
144 where <filename>grub_destination</filename> is set.</para>
145 </listitem>
146
147 <listitem>
148 <para><parameter>grub_destination=&lt;drive&gt;</parameter> -
149 specifies the partition where <filename>GRUB</filename> will be
150 installed</para>
151 </listitem>
152
153 <listitem>
154 <para><parameter>rootfs_destination=&lt;drive&gt;</parameter> -
155 specifies the partition where the <filename>rootfs</filename>
156 will be deployed, used by <filename>GRUB</filename> to boot off
157 of.</para>
158 </listitem>
159
160 <listitem>
161 <para><parameter>rootfs_targz=&lt;rootfs.tar.gz
162 file&gt;</parameter> - the archive of the Enea NFV Access
163 <filename>rootfs</filename> you wish to unpack to where
164 <filename>rootfs_destination</filename> is set. Which file you
165 unpack depends on whether you booting from an SSD/HDD or from a
166 USB drive.</para>
167 </listitem>
168 </orderedlist>
169 </listitem>
170
171 <listitem>
172 <para>Optionally, perform a test run before affecting the actual
173 layout of the physical media with the command: <programlisting>dry</programlisting></para>
174 </listitem>
175
176 <listitem>
177 <para>Run the installer: <programlisting>run</programlisting></para>
178 </listitem>
179
180 <listitem>
181 <para>Exit the script: <programlisting>quit</programlisting></para>
182 </listitem>
183 </orderedlist>
184
185 <para>The Enea NFV Access installer creates a bootable media by
186 performing three steps. Each step is executed or not depending on
187 whether certain parameters are set:</para>
188
189 <orderedlist>
190 <listitem>
191 <para><command>Format drive</command> - creates a 512MB partition
192 which will be used by <filename>GRUB</filename>, and another to be
193 used for the <filename>rootfs</filename> (it should occupy the rest
194 of the physical media minus the first partition). This step depends
195 on the following parameter(s): <programlisting>drive=</programlisting></para>
196 </listitem>
197
198 <listitem>
199 <para><emphasis role="bold">GRUB install</emphasis> - Installs the
200 <literal>grub_binary</literal> on the drive set for
201 <literal>grub_destination</literal>. A <filename>grub.cfg</filename>
202 file will be created that will be configured to boot off of
203 <literal>rootfs_destination</literal>. This step depends on the
204 following parameters:<programlisting>grub_destination=
205grub_binary=
206rootfs_destination=</programlisting></para>
207 </listitem>
208
209 <listitem>
210 <para><emphasis role="bold">Root Filesystem install</emphasis> -
211 Copies and unpacks the files found in
212 <literal>rootfs_targz</literal> to the
213 <literal>rootfs_destination</literal>. This step depends on the
214 following parameters:<programlisting>rootfs_targz=
215rootfs_destination=</programlisting></para>
216 </listitem>
217 </orderedlist>
218
219 <para>After using the installer and setting up the bootable media,
220 connect it to the target machine and configure the target machine to use
221 it as a primary boot device.</para>
222 </section>
223
224 <section id="examples">
225 <title>Examples of Execution</title>
226
227 <para>Below are a few examples of setups that the Enea NFV Access
228 installer can be used for:</para>
229
230 <example id="example_one">
231 <title>Partitioning a drive</title>
232
233 <programlisting>set drive=/dev/sda
234run</programlisting>
235 </example>
236
237 <example id="example_two">
238 <title>Partitioning a drive, installing GRUB and a Root
239 Filesystem:</title>
240
241 <programlisting>set drive=/dev/sda
242set grub_destination=/dev/sda1
243set grub_binary=/home/user/grub-binary.efi
244set rootfs_destination=/dev/sda2
245set rootfs_targz=/home/user/rootfs.tar.gz
246run</programlisting>
247 </example>
248
249 <example id="example_three">
250 <title>Deploying ONLY a root filesystem:</title>
251
252 <programlisting>set rootfs_destination=/dev/sda2
253set rootfs_targz=/home/user/rootfs.tar.gz
254run</programlisting>
255 </example>
256 </section>
257
258 <section id="troubleshooting">
259 <title>Troubleshooting</title>
260
261 <para>GRUB might display the following errors if the default
262 configuration is set to use <filename>hd0</filename> as the primary
263 drive for booting:</para>
264
265 <itemizedlist>
266 <listitem>
267 <para><literal>error: no such partition</literal></para>
268 </listitem>
269
270 <listitem>
271 <para><literal>error: disk not found</literal></para>
272 </listitem>
273 </itemizedlist>
274
275 <para>These errors have two possible causes:</para>
276
277 <itemizedlist>
278 <listitem>
279 <para>The drive where Enea NFV Access was installed is not
280 identified as <literal>hd0</literal> by BIOS.</para>
281 </listitem>
282
283 <listitem>
284 <para>BIOS has assigned the <literal>hd0</literal> label to a
285 different drive (e.g. a USB stick) than the one where Enea NFV
286 Access was installed.</para>
287 </listitem>
288 </itemizedlist>
289
290 <para>To rectify these problems the primary boot drive must be assigned
291 to the correct partition.</para>
292
293 <para><emphasis role="bold">To change the partition for the primary boot
294 drive</emphasis></para>
295
296 <orderedlist>
297 <listitem>
298 <para>Restart the host and in the <filename>GRUB</filename>
299 selection screen, enter the command line by pressing
300 <command>C</command>:</para>
301
302 <mediaobject>
303 <imageobject>
304 <imagedata align="center" contentwidth="600"
305 fileref="images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg" />
306 </imageobject>
307 </mediaobject>
308 </listitem>
309
310 <listitem>
311 <para>List all of the available partitions with
312 <command>ls</command>: <programlisting>partition list example</programlisting></para>
313 </listitem>
314
315 <listitem>
316 <para>In order to identify where Enea NFV Access was installed, for
317 each available partition run <emphasis role="bold">ls
318 &lt;partition&gt;</emphasis>: <programlisting>ls hd0</programlisting></para>
319 </listitem>
320
321 <listitem>
322 <para>After identifying the partition, return to the GRUB selection
323 screen by pressing <command>esc</command></para>
324 </listitem>
325
326 <listitem>
327 <para>Press <command>e</command> to edit and set the boot partition
328 to the one identified previously: <programlisting>edit and set partition example</programlisting></para>
329 </listitem>
330
331 <listitem>
332 <para>To reboot to see if the change worked, press:
333 <command>F10</command></para>
334 </listitem>
335 </orderedlist>
336 </section>
337 </section>
338
339 <section condition="hidden" id="release-content"> 45 <section condition="hidden" id="release-content">
340 <title>NFV Access Release content</title> 46 <title>NFV Access Release content</title>
341 47