summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
diff options
context:
space:
mode:
authormrpa <miruna.paun@enea.com>2020-11-18 15:28:24 +0100
committermrpa <miruna.paun@enea.com>2020-11-18 15:29:51 +0100
commitd78fae86a57e8847e1c52e12aaf7468ff0227815 (patch)
tree03f436fec9ab325568f50d9570828c865e01a374 /doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
parente220d50138c2b7539a646225cdc375f858f75f9f (diff)
downloadnfv-access-documentation-d78fae86a57e8847e1c52e12aaf7468ff0227815.tar.gz
Refactoring of Getting started merging to Develop
from branch feature_AP-581. Change-Id: I67474ec6badaa279e8c56fca9bb50aec98de8e5f Signed-off-by: mrpa <miruna.paun@enea.com>
Diffstat (limited to 'doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml')
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml537
1 files changed, 537 insertions, 0 deletions
diff --git a/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
new file mode 100644
index 0000000..4b1a7dc
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
@@ -0,0 +1,537 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="upgrade_ena">
3 <title>Upgrading NFV Access</title>
4
5 <para>Enea provides regular releases that will require the upgrading of NFV
6 Access components. The uCPE Manager must be upgraded to the new Enea NFV
7 Access version before the uCPE devices are.</para>
8
9 <section id="upgrade_mg">
10 <title>Upgrading the uCPE Manager</title>
11
12 <orderedlist>
13 <listitem>
14 <para>Unzip the
15 <filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
16 folder.</para>
17
18 <para>The directory in which the archive has been unpacked will be
19 denoted as <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
20 </listitem>
21
22 <listitem>
23 <para>Enter <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
24 </listitem>
25
26 <listitem>
27 <para>Run the following command with the root account and change
28 <literal>/opt/ems</literal> to the correct location of the uCPE
29 Manager installation:</para>
30
31 <programlisting>./upgrade.sh /opt/ems \
32Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
33 </listitem>
34 </orderedlist>
35
36 <para>Running this command will:</para>
37
38 <itemizedlist>
39 <listitem>
40 <para>Stop the currently running <literal>ucpemanager</literal>
41 service.</para>
42 </listitem>
43
44 <listitem>
45 <para>Create a compressed file of the <literal>ucpemanager</literal>
46 application folder
47 (<filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>), which
48 contains a snapshot of the existing installation.</para>
49
50 <note>
51 <para>The snapshot file created during the upgrade can be used for
52 restoring the uCPE Manager.</para>
53 </note>
54 </listitem>
55
56 <listitem>
57 <para>Extract the application files from the specified compressed
58 install kit.</para>
59 </listitem>
60
61 <listitem>
62 <para>Start the <literal>ucpemanager</literal> service.</para>
63 </listitem>
64 </itemizedlist>
65
66 <section id="restore_prev_ucpe_install">
67 <title>Restoring a previous uCPE Manager installation</title>
68
69 <para><emphasis role="bold">How to restore a previous uCPE Manager
70 installation</emphasis></para>
71
72 <orderedlist>
73 <listitem>
74 <para>Unzip
75 <filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
76 </listitem>
77
78 <listitem>
79 <para>The directory in which the archive has been unpacked will be
80 denoted as <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
81 </listitem>
82
83 <listitem>
84 <para>Copy the snapshot file
85 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>)
86 created during a previous uCPE Manager Upgrade or uCPE Manager
87 Uninstall Operation into the
88 <literal>&lt;uCPEM-installdir&gt;</literal> directory.</para>
89 </listitem>
90
91 <listitem>
92 <para>Enter <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
93 </listitem>
94
95 <listitem>
96 <para>Run the following command with the root user and change
97 <literal>/opt/ems</literal> to the correct location of the uCPE
98 Manager installation:</para>
99
100 <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
101 </listitem>
102 </orderedlist>
103
104 <para>Running this command will:</para>
105
106 <itemizedlist>
107 <listitem>
108 <para>Remove any vestiges of the existing
109 <literal>ucpemanager</literal> service, if they exist.</para>
110 </listitem>
111
112 <listitem>
113 <para>Reinstall the uCPE Manager application on the specified target
114 location, restoring the data in the database and files in the
115 process.</para>
116 </listitem>
117 </itemizedlist>
118
119 <para>The <literal>ucpemanager</literal> service will then start with
120 the older version now running on the system.</para>
121 </section>
122
123 <section id="uninstall_ucpem_install">
124 <title>Uninstalling an existing uCPE Manager installation</title>
125
126 <para><emphasis role="bold">How to uninstall an existing uCPE Manager
127 installation</emphasis></para>
128
129 <orderedlist>
130 <listitem>
131 <para>Navigate to the folder where the uCPE Manager is
132 installed.</para>
133 </listitem>
134
135 <listitem>
136 <para>Run the following command with the root user and change
137 <literal>/opt/ems</literal> to the correct location of the uCPE
138 Manager installation:</para>
139
140 <programlisting>./uninstall.sh /opt/ems</programlisting>
141 </listitem>
142 </orderedlist>
143
144 <para>Running this command will:</para>
145
146 <itemizedlist>
147 <listitem>
148 <para>Stop the currently running <literal>ucpemanager</literal>
149 service.</para>
150 </listitem>
151
152 <listitem>
153 <para>Create a compressed file of the <literal>ucpemanager</literal>
154 application folder:
155 <filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>, which
156 contains a snapshot of the existing installation and functions as a
157 restore point.</para>
158
159 <note>
160 <para>The snapshot file created during the uninstall can be used
161 for restoring the uCPE Manager.</para>
162 </note>
163 </listitem>
164
165 <listitem>
166 <para>Uninstall the <literal>ucpemanager</literal> service, so that
167 it will not startup on reboot.</para>
168 </listitem>
169
170 <listitem>
171 <para>Uninstall the database service.</para>
172 </listitem>
173
174 <listitem>
175 <para>Completely remove the contents of the application and database
176 folders.</para>
177 </listitem>
178 </itemizedlist>
179
180 <para>After these steps, the uCPE Manager is completely removed from the
181 system.</para>
182 </section>
183 </section>
184
185 <section id="upgrade_devices">
186 <title>uCPE device upgrades</title>
187
188 <para>A uCPE device can be upgraded using the uCPE Manager GUI.</para>
189
190 <section id="device_up_process">
191 <title>The uCPE device upgrade process</title>
192
193 <para>The Device Upgrade/Install option performs the following
194 operations to the uCPE device:</para>
195
196 <orderedlist>
197 <listitem>
198 <para><emphasis role="bold">Prepare for upgrade.</emphasis> This
199 stage prepares the files needed for an upgrade.</para>
200 </listitem>
201
202 <listitem>
203 <para><emphasis role="bold">Install file on device.</emphasis> This
204 stage copies the file to the uCPE device.</para>
205 </listitem>
206
207 <listitem>
208 <para><emphasis role="bold">Upgrade Device.</emphasis> This stage
209 upgrades the uCPE device to a newer version.</para>
210 </listitem>
211 </orderedlist>
212 </section>
213
214 <section id="mg_upgrade">
215 <title>Managing the Device Upgrade</title>
216
217 <para>Before an installation or upgrade can be completed, certain
218 configuration data must be set. Files also need to be uploaded to the
219 Device Upgrade image repository to be uploaded to the device.</para>
220
221 <para>Launch the Device Upgrade management console by selecting
222 <literal>Devices</literal> -&gt; <literal>Upgrade</literal> from the top
223 tool-bar. The console will contain the following tabs:</para>
224
225 <itemizedlist>
226 <listitem>
227 <para><literal>Image Library</literal>. To add/delete an
228 image.</para>
229 </listitem>
230
231 <listitem>
232 <para><literal>Upgrade Operations</literal>. See running upgrades,
233 cancel any upgrades in progress, start a uCPE device upgrade.</para>
234 </listitem>
235
236 <listitem>
237 <para><literal>Configuration</literal>. Upgrade configuration
238 parameters.</para>
239 </listitem>
240 </itemizedlist>
241
242 <para>Press Close when the message <literal>File Uploaded
243 Successfully</literal> appears on the File Upload Screen.</para>
244
245 <note>
246 <para>The uCPE Device upgrade is done with image files of type
247 <literal>rootfs.ostree.tar.bz2</literal>, which are available in the
248 <filename>Enea_NFV_Ac-cess_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
249 file you downloaded with your release.</para>
250 </note>
251
252 <section id="image_lib">
253 <title>Image Library</title>
254
255 <para><emphasis role="bold">Adding an image to the image
256 repository/library</emphasis><orderedlist>
257 <listitem>
258 <para>Select <literal>Devices</literal> -&gt;
259 <literal>Upgrade</literal>.</para>
260 </listitem>
261
262 <listitem>
263 <para>Select <literal>Add</literal> from the <literal>Image
264 Library</literal> tab to add a new image file.</para>
265 </listitem>
266
267 <listitem>
268 <para>Click on <literal>Choose File</literal> to provide the
269 path to the image file (must be of type
270 <literal>rootfs.os-tree.tar.bz2</literal>).</para>
271 </listitem>
272
273 <listitem>
274 <para>Select the target hardware platform corresponding to the
275 image being uploaded (<literal>xeon-d</literal> or
276 <literal>atom-c3000</literal>).</para>
277 </listitem>
278
279 <listitem>
280 <para>Click <literal>Send</literal> to upload the image to the
281 image repository.</para>
282 </listitem>
283 </orderedlist></para>
284
285 <para><emphasis role="bold">Deleting an image from the image
286 repository</emphasis></para>
287
288 <orderedlist>
289 <listitem>
290 <para>Select <literal>Devices</literal> -&gt;
291 <literal>Upgrade</literal>.</para>
292 </listitem>
293
294 <listitem>
295 <para>Select the image you want to delete from the <literal>Image
296 Library</literal> tab and then click
297 <literal>Delete</literal>.</para>
298 </listitem>
299 </orderedlist>
300 </section>
301
302 <section id="upgrade_options">
303 <title>Upgrade Operations</title>
304
305 <para>The <literal>Upgrade Operations</literal> tab allows a user to
306 manage uCPE device upgrades in the system. It allows the user to see
307 all the upgrades that are currently in progress, as well as listing
308 the completed ones. If an upgrade succeeds or fails, then a row will
309 be added to the completed upgrades table. If one fails, the failure
310 message will be visible in the table.</para>
311
312 <note>
313 <para>The list of completed upgrade tasks resides in the cache
314 memory and will not persist across reboots of the server.</para>
315 </note>
316
317 <para><emphasis role="bold">How to Install/Upgrade a device
318 immediately or schedule the process for later</emphasis><orderedlist>
319 <listitem>
320 <para>Select <literal>Devices</literal> -&gt;
321 <literal>Upgrade</literal>.</para>
322 </listitem>
323
324 <listitem>
325 <para>Select <literal>Upgrade Devices</literal> from the
326 <literal>Upgrade Operations</literal> tab. This will launch a
327 <literal>Multi Device Install Image</literal> screen that will
328 allow the user to install and upgrade more than one uCPE device
329 at a time or upgrade later.</para>
330 </listitem>
331 </orderedlist></para>
332
333 <para>The configurable parameters are:</para>
334
335 <itemizedlist>
336 <listitem>
337 <para><literal>Scheduling</literal>. Click this checkbox if the
338 upgrade will be done later. Schedule the day, hour and minute for
339 when to run the upgrade.</para>
340
341 <note>
342 <para>The hour represents the local uCPE Manager server
343 hour.</para>
344 </note>
345 </listitem>
346
347 <listitem>
348 <para><literal>Description</literal>. An optional description of
349 the operation. It is recommended to add a description so that
350 different upgrades happening simultaneously can be
351 distinguished.</para>
352 </listitem>
353
354 <listitem>
355 <para><literal>Image File</literal>. Click on <literal>Choose
356 Image File</literal> to select the image file.</para>
357 </listitem>
358
359 <listitem>
360 <para><literal>Devices</literal>. The list of uCPE Devices that
361 can accept an image file is populated when the image file is
362 chosen.</para>
363
364 <para>Press the <literal>&gt;</literal> button to move the uCPE
365 devices to the right side of the selector. Those chosen form the
366 list of uCPE devices that will be upgraded.</para>
367 </listitem>
368
369 <listitem>
370 <para>Upgrade Operation. The available options are:</para>
371
372 <itemizedlist>
373 <listitem>
374 <para><literal>Install and Activate</literal>. This will do an
375 image installation as well as an upgrade.</para>
376 </listitem>
377
378 <listitem>
379 <para><literal>Install Only</literal>. This will do an image
380 installation only. The image is copied to the uCPE device, and
381 an upgrade will be done later either at a scheduled time or
382 when the option <literal>Activate Only</literal> is
383 selected.</para>
384 </listitem>
385
386 <listitem>
387 <para><literal>Activate Only</literal>. This will activate an
388 already installed image on the uCPE device.</para>
389 </listitem>
390 </itemizedlist>
391 </listitem>
392 </itemizedlist>
393
394 <note>
395 <para>When the uCPE device activates the upgrade, it will be
396 rebooted automatically.</para>
397 </note>
398 </section>
399
400 <section id="releases_installed">
401 <title>Releases installed on a uCPE device</title>
402
403 <para>The installed releases on a uCPE device can be viewed by
404 selecting the uCPE device first, then from the top toolbar selecting
405 <literal>Configuration</literal> -&gt;
406 <literal>Upgrade</literal>.</para>
407
408 <para>The installed releases on the uCPE device, the release status,
409 release state, <literal>commit-id</literal> and release version will
410 be listed in a table.</para>
411 </section>
412
413 <section id="upgrade_status">
414 <title>uCPE device upgrade status</title>
415
416 <para>The status of the installation and upgrade can be viewed in the
417 <literal>Upgrade Operations</literal> tab. Ongoing or scheduled
418 upgrade operations can be viewed or cancelled.</para>
419
420 <para><emphasis role="bold">To view the status of an installation or
421 upgrade operations</emphasis></para>
422
423 <orderedlist>
424 <listitem>
425 <para>Select <literal>Devices</literal> -&gt;
426 <literal>Upgrade</literal>.</para>
427 </listitem>
428
429 <listitem>
430 <para>Select <literal>Upgrade Operations</literal>. The ongoing
431 operations are listed at the top and a history of failed or
432 successful operations are listed at the bottom.</para>
433 </listitem>
434
435 <listitem>
436 <para>Select an <literal>Active</literal> or <literal>Completed
437 Upgrade Operation</literal> and click the <literal>Device
438 Status</literal> button to see detailed information regarding the
439 upgrade operation, including the uCPE devices involved and
440 information per uCPE device.</para>
441 </listitem>
442 </orderedlist>
443
444 <para><emphasis role="bold">To cancel an upgrade
445 operation</emphasis></para>
446
447 <orderedlist>
448 <listitem>
449 <para>Select <literal>Devices</literal> -&gt;
450 <literal>Upgrade</literal> -&gt; <literal>Upgrade
451 Operations</literal>.</para>
452 </listitem>
453
454 <listitem>
455 <para>Select an operation from the list and press <literal>Cancel
456 Upgrade</literal> and <literal>Confirm</literal>. The operation
457 will then be deleted from the list.</para>
458 </listitem>
459 </orderedlist>
460 </section>
461
462 <section id="config">
463 <title>Configuration</title>
464
465 <note>
466 <para>The default values present in the configuration of each uCPE
467 device are recommended for use. Modifying them is for an Advanced
468 User only.</para>
469 </note>
470
471 <para><emphasis role="bold">How to Configure the uCPE device
472 Upgrade</emphasis><orderedlist>
473 <listitem>
474 <para>Select <literal>Devices</literal> -&gt;
475 <literal>Upgrade</literal>.</para>
476 </listitem>
477
478 <listitem>
479 <para>Select <literal>Configuration</literal>.</para>
480 </listitem>
481
482 <listitem>
483 <para>The configurable parameters are:</para>
484
485 <itemizedlist>
486 <listitem>
487 <para><literal>deviceImageDir</literal>. This is the disk
488 location of the device image repository.</para>
489
490 <note>
491 <para>If no absolute path name is given it is assumed to
492 be relative to the installation directory.</para>
493 </note>
494 </listitem>
495
496 <listitem>
497 <para><literal>maxThreads</literal>. This number dictates
498 how many upgrades the system can manage at one time, either
499 individually launched or launched from the multi-device
500 screens. This value defaults to 20, which means that 20 uCPE
501 devices may be updated at one time.</para>
502 </listitem>
503
504 <listitem>
505 <para><literal>KeepAlive</literal>. This number represents
506 the number of seconds that a thread will be kept alive
507 before it is collected. If multiple installations are
508 occurring, this will keep the thread alive for X seconds
509 before it is released. If not released, it can be used by
510 the internal scheduling system as soon as it has completed
511 an upgrade.</para>
512 </listitem>
513 </itemizedlist>
514 </listitem>
515 </orderedlist></para>
516 </section>
517
518 <section id="related_functionality">
519 <title>Related Functionality for a uCPE device upgrade</title>
520
521 <para>Each uCPE device can receive image files and use them to
522 upgrade. This can be done by selecting the uCPE device in the
523 <literal>System</literal> view and clicking the
524 <literal>Upgrade</literal> button. In the new window, an upgrade image
525 can be chosen from the <literal>Image Files</literal> tab by selecting
526 the image file from the list and clicking the <literal>Install on
527 Device</literal> button.</para>
528
529 <para>Once an image is installed on the uCPE device, the image will be
530 available on the uCPE device and be visible in the
531 <literal>Releases</literal> tab. It can then be selected from the list
532 and the upgrade started by clicking the <literal>Upgrade</literal>
533 button.</para>
534 </section>
535 </section>
536 </section>
537</chapter> \ No newline at end of file
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-07-06 09:52:01 +0000