1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
OpenBMC non-UBI Code Update
===================
Two BMC Code Updates layouts are available:
* Static, non-UBI layout - The default code update
* UBI layout - enabled via obmc-ubi-fs machine feature
This document describes the non-UBI, default code update. The UBI code update
can be found here: [ubi-code-update.md](ubi-code-update.md)
The host code update can be found here:
[host-code-update.md](host-code-update.md)
After building OpenBMC, you will end up with a set of image files in
`tmp/deploy/images/<platform>/`. The `image-*` symlinks correspond to components
that can be updated on the BMC:
* `image-bmc` → `obmc-phosphor-image-<platform>-<timestamp>.static.mtd`
The complete flash image for the BMC
* `image-kernel` → `fitImage-obmc-phosphor-initramfs-<platform>.bin`
The OpenBMC kernel FIT image (including the kernel, device tree, and initramfs)
* `image-rofs` → `obmc-phosphor-image-<platform>.squashfs-xz`
The read-only OpenBMC filesystem
* `image-rwfs` → `rwfs.jffs2`
The read-write filesystem for persistent changes to the OpenBMC filesystem
* `image-u-boot` → `u-boot.bin`
The OpenBMC bootloader
Additionally, there are two tarballs created that can be deployed and unpacked by REST:
* `<platform>-<timestamp>.all.tar`
The complete BMC flash content: A single file (`image-bmc`) wrapped in a
tar archive.
* `<platform>-<timestamp>.tar`
Partitioned BMC flash content: Multiple files wrapped in a tar archive,
one for each of the u-boot, kernel, ro and rw partitions.
Preparing for BMC code Update
-----------------------------
The BMC normally runs with the read-write and read-only file systems
mounted, which means these images may be read (and written, for the
read-write filesystem) at any time. Because the updates are distributed
as complete file system images, these filesystems have to be unmounted
to replace them with new images. To unmount these file systems all
applications must be stopped.
By default, an orderly `reboot` will stop all applications and unmount
the root filesystem, and the images copied into the `/run/initramfs`
directory will be applied at that point before restarting. This also
applied to the `shutdown` and `halt` commands -- they will write the
flash before stopping.
As an alternative, an option can be parsed by the `init` script in
the initramfs to copy the required contents of these filesystems into
RAM so the images can be applied while the rest of the application stack
is running and progress can be monitored over the network. The
`update` script can then be called to write the images while the
system is operational and its progress output monitored.
Update from the OpenBMC shell
-----------------------------
To update from the OpenBMC shell, follow the steps in this section.
It is recommended that the BMC be prepared for update (note that the
environment variable needs to be set twice for initramfs be able to
read it due to the U-Boot redundant environments):
fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
reboot
Copy one or more of these `image-*` files to the directory:
/run/initramfs/
(preserving the filename), then run the `update` script to apply the images:
/run/initramfs/update
then reboot to finish applying:
reboot
During the reboot process, the `update` script will be invoked after
the file systems are unmounted to complete the update process.
Some optional features are available, see the help for more details:
/run/initramfs/update --help
Update via REST
---------------
An OpenBMC system can download an update image from a TFTP server, and apply
updates, controlled via REST. The general procedure is:
1. Prepare system for update
2. Configure update settings
3. Initiate update
4. Check flash status
5. Apply update
6. Reboot the BMC
### Prepare system for update
Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc` object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/prepareForUpdate
This will setup the u-boot environment and reboot the BMC. If no other
images were pending the BMC should return in about 2 minutes.
### Configure update settings
There are a few settings available to control the update process:
* `preserve_network_settings`: Preserve network settings, only needed if updating the whole flash
* `restore_application_defaults`: update (clear) the read-write file system
* `update_kernel_and_apps`: update kernel and initramfs.
If the partitioned tarball will be used for update then this option
must be set. Otherwise, if the complete tarball will be used then
this option must not be set.
* `clear_persistent_files`: ignore the persistent file list when resetting applications defaults
* `auto_apply`: Attempt to write the images by invoking the `Apply` method after the images are unpacked.
To configure the update settings, perform a REST PUT to
`/control/flash/bmc/attr/<setting>`. For example:
curl -b cjar -k -H "Content-Type: application/json" -X PUT \
-d '{"data": 1}' \
https://${bmc}/org/openbmc/control/flash/bmc/attr/preserve_network_settings
### Initiate update
Perform a POST to invoke the `updateViaTftp` method of the `/flash/bmc` object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": ["<TFTP server IP address>", "<filename>"]}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/updateViaTftp
Note the `<filename>` shall be a tarball.
### Check flash status
You can query the progress of the download and image verification with
a simple GET request:
curl -b cjar -k https://${bmc}/org/openbmc/control/flash/bmc
Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc` object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/GetUpdateProgress
Note:
* During downloading the tarball, the progress status is `Downloading`
* After the tarball is downloaded and verified, the progress status becomes `Image ready to apply`.
### Apply update
If the status is `Image ready to apply.` then you can either initiate
a reboot or call the Apply method to start the process of writing the
flash:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/Apply
Now the image is being flashed, you can check the progress with above steps command as well.
* During flashing the image, the status becomes `Writing images to flash`
* After it's flashed and verified, the status becomes `Apply Complete. Reboot to take effect.`
### Reboot the BMC
To start using the new images, reboot the BMC using the warmReset method
of the BMC control object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/bmc0/action/warmReset
|
