1# OpenBMC Webserver Development 2 31. ### Performance targets 4 As OpenBMC is intended to be deployed on an embedded system, care should be 5 taken to avoid expensive constructs, and memory usage. In general, our 6 performance and metric targets are: 7 8 - Binaries and static files should take up < 1MB of filesystem size 9 - Memory usage should remain below 10MB at all times 10 - Application startup time should be less than 1 second on target hardware 11 (AST2500) 12 132. ### Asynchronous programming 14 Care should be taken to ensure that all code is written to be asynchronous in 15 nature, to avoid blocking methods from stopping the processing of other 16 tasks. At this time the webserver uses boost::asio for it async framework. 17 Threads should be avoided if possible, and instead use async tasks within 18 boost::asio. 19 203. ### Secure coding guidelines 21 Secure coding practices should be followed in all places in the webserver 22 23 In general, this means: 24 - All buffer boundaries must be checked before indexing or using values 25 - All pointers and iterators must be checked for null before dereferencing 26 - All input from outside the application is considered untrusted, and should 27 be escaped, authorized and filtered accordingly. This includes files in 28 the filesystem. 29 - All error statuses are checked and accounted for in control flow. 30 - Where applicable, noexcept methods should be preferred to methods that use 31 exceptions 32 - Explicitly bounded types should be preferred over implicitly bounded types 33 (like std::array<int, size> as opposed to int[size]) 34 - no use of [Banned 35 functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions 36 "Banned function list") 37 384. ### Error handling 39 Error handling should be constructed in such a way that all possible errors 40 return valid HTTP responses. The following HTTP codes will be used commonly 41 - 200 OK - Request was properly handled 42 - 201 Created - Resource was created 43 - 401 Unauthorized - Request didn't posses the necessary authentication 44 - 403 Forbidden - Request was authenticated, but did not have the necessary 45 permissions to accomplish the requested task 46 - 404 Not found - The url was not found 47 - 500 Internal error - Something has broken within the OpenBMC web server, 48 and should be filed as a bug 49 50 Where possible, 307 and 308 redirects should be avoided, as they introduce 51 the possibility for subtle security bugs. 52 535. ### Startup times 54 Given that the most common target of OpenBMC is an ARM11 processor, care 55 needs to be taken to ensure startup times are low. In general this means: 56 57 - Minimizing the number of files read from disk at startup. Unless a 58 feature is explicitly intended to be runtime configurable, its logic 59 should be "baked in" to the application at compile time. For cases where 60 the implementation is configurable at runtime, the default values should 61 be included in application code to minimize the use of nonvolatile 62 storage. 63 - Avoid excessive memory usage and mallocs at startup. 64 656. ### Compiler features 66 - At this point in time, the webserver sets a number of security flags in 67 compile time options to prevent misuse. The specific flags and what 68 optimization levels they are enabled at are documented in the 69 CMakeLists.txt file. 70 - Exceptions are currently enabled for webserver builds, but their use is 71 discouraged. Long term, the intent is to disable exceptions, so any use 72 of them for explicit control flow will likely be rejected in code review. 73 Any use of exceptions should be cases where the program can be reasonably 74 expected to crash if the exception occurs, as this will be the future 75 behavior once exceptions are disabled. 76 - Run time type information is disabled 77 - Link time optimization is enabled 78 797. ### Authentication 80 The webserver shall provide the following authentication mechanisms. 81 - Basic authentication 82 - Cookie authentication 83 - Token authentication 84 85 There shall be connection between the authentication mechanism used and 86 resources that are available over it. The webserver shall employ an 87 authentication scheme that is in line with the rest of OpenBMC, and allows 88 users and privileges to be provisioned from other interfaces. 89 908. ### Web security 91 The OpenBMC webserver shall follow the latest OWASP recommendations for 92 authentication, session management, and security. 93 949. ### Performance 95 The performance priorities for the OpenBMC webserver are (in order): 96 1. Code is readable and clear 97 2. Code follows secure guidelines 98 3. Code is performant, and does not unnecessarily abstract concepts at the 99 expense of performance 100 4. Code does not employ constructs which require continuous system 101 resources, unless required to meet performance targets. (example: 102 caching sensor values which are expected to change regularly) 103 10410. ### Abstraction/interfacing 105 In general, the OpenBMC webserver is built using the data driven design. 106 Abstraction and Interface guarantees should be used when multiple 107 implementations exist, but for implementations where only a single 108 implementation exists, prefer to make the code correct and clean rather than 109 implement a concrete interface. 110 11111. ### phosphor webui 112 The webserver should be capable of hosting phosphor-webui, and implementing 113 the required flows to host the application. In general, all access methods 114 should be available to the webui. 115 11612. ### Redfish 117 bmcweb's Redfish implementation, including Redfish OEM Resources, shall 118 conform to the Redfish specification. Please keep bmcweb's [Redfish support 119 document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) updated. 120 OEM schemas should conform and be developed in line with the rules in 121 [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md). 122 12313. ### Common errors 124 A number of examples of common errors are captured in the common errors doc. 125 It is recommended that developers read and understand all of them before 126 starting any openbmc development. 127 [Common Errors](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md). 128 12914. ### Developing and Testing 130 There are a variety of ways to develop and test bmcweb software changes. 131 Here are the steps for using the SDK and QEMU. 132 133 - Follow all [development environment setup](https://github.com/openbmc/docs/blob/master/development/dev-environment.md) 134 directions in the development environment setup document. This will get 135 QEMU started up and you in the SDK environment. 136 - Follow all of the [gerrit setup](https://github.com/openbmc/docs/blob/master/development/gerrit-setup.md) 137 directions in the gerrit setup document. 138 - Clone bmcweb from gerrit 139 ``` 140 git clone ssh://openbmc.gerrit/bmcweb/ 141 ``` 142 143 - Ensure it compiles 144 ``` 145 cmake ./ && make 146 ``` 147 **Note:** If you'd like to enable debug traces in bmcweb, use the 148 following command for cmake 149 ``` 150 cmake ./ -DCMAKE_BUILD_TYPE:type=Debug 151 ``` 152 153 - Make your changes as needed, rebuild with `make` 154 155 - Reduce binary size by stripping it when ready for testing 156 ``` 157 arm-openbmc-linux-gnueabi-strip bmcweb 158 ``` 159 **Note:** Stripping is not required and having the debug symbols could be 160 useful depending on your testing. Leaving them will drastically increase 161 your transfer time to the BMC. 162 163 - Copy your bmcweb you want to test to /tmp/ in QEMU 164 ``` 165 scp -P 2222 bmcweb root@127.0.0.1:/tmp/ 166 ``` 167 **Special Notes:** 168 The address and port shown here (127.0.0.1 and 2222) reaches the QEMU session 169 you set up in your development environment as described above. 170 171 - Stop bmcweb service within your QEMU session 172 ``` 173 systemctl stop bmcweb 174 ``` 175 **Note:** bmcweb supports being started directly in parallel with the bmcweb 176 running as a service. The standalone bmcweb will be available on port 18080. 177 An advantage of this is you can compare between the two easily for testing. 178 In QEMU you would need to open up port 18080 when starting QEMU. Your curl 179 commands would need to use 18080 to communicate. 180 181 - If running within a system that has read-only /usr/ filesystem, issue 182 the following commands one time per QEMU boot to make the filesystem 183 writeable 184 ``` 185 mkdir -p /var/persist/usr 186 mkdir -p /var/persist/work/usr 187 mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr 188 ``` 189 190 - Remove the existing bmcweb from the filesystem in QEMU 191 ``` 192 rm /usr/bin/bmcweb 193 ``` 194 195 - Link to your new bmcweb in /tmp/ 196 ``` 197 ln -sf /tmp/bmcweb /usr/bin/bmcweb 198 ``` 199 200 - Test your changes. bmcweb will be started automatically upon your 201 first REST or Redfish command 202 ``` 203 curl -c cjar -b cjar -k -X POST https://127.0.0.1:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 204 curl -c cjar -b cjar -k -X GET https://127.0.0.1:2443/xyz/openbmc_project/state/bmc0 205 ``` 206 207 - Stop the bmcweb service and scp new file over to /tmp/ each time you 208 want to retest a change. 209 210 See the [REST](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md) 211 and [Redfish](https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md) cheatsheets for valid commands. 212 213 Please test all Redfish changes with the 214 [Redfish Service Validator](https://github.com/DMTF/Redfish-Service-Validator). 215 Your change should not introduce any new validator errors. Please include 216 the Redfish Service Validator results as part of the commit message 217 ["Tested" field](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#testing). 218 219## clang-tidy 220 221clang-tidy is a tool that can be used to identify coding style violations, bad 222design patterns, and bug prone constructs. The checks are implemented in the 223.clang-tidy file in the root of bmcweb, and are expected to be passing. To 224run, the best way is to run the checks in yocto. 225 226``` 227# check out meta-clang in your openbmc root 228cd openbmc 229git clone https://github.com/kraj/meta-clang 230 231# add the meta-clang layer to BBLAYERS in $BBPATH/conf/bblayers.conf 232<path_to_your_build_dir>/meta-clang 233 234# Add this line to $BBPATH/conf/local.conf to build bmcweb with clang 235TOOLCHAIN_pn-bmcweb = "clang" 236 237# and build 238bitbake bmcweb 239 240# Open devshell (this will open a shell) 241bitbake -c devshell bmcweb 242 243# cd into the work dir 244cd oe-workdir/bmcweb-1.0+git999 245# run clang tidy 246clang-tidy --header-filter=".*" -p . $BBPATH/workspace/sources/bmcweb/src/webserver_main.cpp 247``` 248