blob: 2ebea504deefda90e92a6c7ab7de92ebbcbf813a [file] [log] [blame]
Charles Chandd26eeb2019-08-29 17:59:21 -07001.. |onos_version| replace:: 1.12.2
2
Charles Chan78a737f2019-09-12 13:55:22 -07003Installation Guide
4******************
Zack Williams553a3632019-08-09 17:14:43 -07005
Charles Chan4d5ee192019-09-09 23:08:36 -07006Building a Hardware Pod
7=======================
8See :doc:`Supported Hardware <supported-hardware>` for details.
Charles Chandd26eeb2019-08-29 17:59:21 -07009
10
11Install Controller - ONOS
12=========================
13You could run Trellis with a `single instance of ONOS <https://wiki.onosproject.org/display/ONOS/Local+workflow>`_. But it is recommended to run ONOS as a cluster.
14
15The idea is to have a "build machine", where you host and build ONOS source code. But to launch it in operation you use other "target machines" (VMs, containers or servers).
16Typically we use `STC <https://wiki.onosproject.org/pages/viewpage.action?pageId=12421025>`_ to launch ONOS ins 3 target machines which form a ONOS cluster.
17
18
19Download ONOS |onos_version|
20---------------------------------
21Trellis currently is released as part of ONOS and therefore it follows ONOS version number.
22This document is written based on ONOS |onos_version|.
23
24You can find more information about how to setup build environment and fetch ONOS source code from `Development Environment Setup <https://wiki.onosproject.org/display/ONOS/Development+Environment+Setup>`_.
25
26
27Prepare Your Target Machine
28---------------------------
29Please refer to `target machines requirements <https://wiki.onosproject.org/display/ONOS/Cells+and+ONOS+test+scripts#CellsandONOStestscripts-Targetmachinesrequirements>`_ for details (you only have to do this once).
30
31You do not need to follow the directions for the "Mininet Target Machine" if you are using hardware switches.
32
33
34Create a Cell File
35--------------------
36We need to compose a cell file in order to give the information about target machines to the build machine. Please refer to `test cells <https://wiki.onosproject.org/display/ONOS/Cells+and+ONOS+test+scripts#CellsandONOStestscripts-TestCells>`_ for details. For example:
37
38.. code-block:: bash
39
40 export ONOS_CELL=menlo
41 export OC1=10.128.0.216
42 export OC2=10.128.0.217
43 export OC3=10.128.0.218
44 export ONOS_APPS=drivers,gui,openflow,segmentrouting,fpm,dhcprelay,routeradvertisement,hostprobingprovider,t3
45 export ONOS_USER=admin
46 export ONOS_GROUP=admin
47 export ONOS_USE_SSH=true
48 export ONOS_WEB_USER=onos
49 export ONOS_WEB_PASS=rocks
50
51- ``OC1, OC2, OC3`` are the IP addresses of the 3 target machines where the ONOS cluster will be deployed.
52- ``ONOS_APPS`` are the apps you want to automatically deploy at launch.
53
54 - ``drivers`` includes drivers for various devices and pipelines. Always required.
55 - ``gui`` enables graphic user interface. Highly recommended.
56 - ``openflow`` is a meta app that loads ``openflow-base``, ``lldpprovider`` and ``hostprovider``. Always required.
57 - ``segmentrouting`` controls forwarding in the fabric. Always required.
58 - ``fpm`` (Forwarding Plane Manager) exchanges forwarding information with Quagga. Required if connecting to external router.
59 - ``dhcprelay`` relays DHCP packets between clients and servers. Required if using DHCP to configure IP addresses for hosts
60 - ``routeradvertisement`` periodically sends IPv6 router advertisement packets on configured interfaces. Required if using IPv6
61 - ``hostprobingprovider`` probes and verifies locations of dual-homed hosts. Required if using dual-homing feature with paired switches
62 - ``t3`` (Trellis Troubleshooting Tool) is very useful for debugging. Highly recommended.
63
64- ``ONOS_USER`` is used to login to the target machines,
65 and the password is not required as you have setup the target machines for password-less access over ssh.
66
67Once that's done, you can use the ``cell`` command to load the cell file.
68
69.. code-block:: console
70
71 $ source onos/tools/dev/bash_profile
72 $ cell menlo
73
74
75Check Your Target Environment
76-----------------------------
77Check if your environment is OK with ``stc prerequisites`` (you only have to do this once).
78
79.. code-block:: console
80
81 $ stc prerequisites
82 2017-02-07 12:10:23 Prerequisites started
83 2017-02-07 12:10:23 Check-Passwordless-Login-1 started -- ssh -n -o ConnectTimeout=3 -o PasswordAuthentication=no admin@10.128.0.216 date
84 2017-02-07 12:10:23 Check-ONOS-Bits started -- onos-check-bits
85 2017-02-07 12:10:23 Check-Passwordless-Login-3 started -- ssh -n -o ConnectTimeout=3 -o PasswordAuthentication=no admin@10.128.0.218 date
86 2017-02-07 12:10:23 Check-Passwordless-Login-2 started -- ssh -n -o ConnectTimeout=3 -o PasswordAuthentication=no admin@10.128.0.217 date
87 2017-02-07 12:10:23 Check-Environment started -- test -n /Users/sauravdas/onos -a -n 10.128.0.* -a -n 10.128.0.216
88 2017-02-07 12:10:23 Check-Environment completed
89 2017-02-07 12:10:23 Check-Passwordless-Login-1 completed
90 2017-02-07 12:10:23 Check-Passwordless-Login-2 completed
91 2017-02-07 12:10:23 Check-Passwordless-Login-3 completed
92 2017-02-07 12:10:25 Check-ONOS-Bits completed
93 2017-02-07 12:10:25 Prerequisites completed
94 0:01 Passed! 6 steps succeeded
95
96
97Launch STC Command
98------------------
99Finally launch with ``stc setup`` once you have built ONOS. Here is what it looks like when I launch
100
101.. code-block:: console
102
103 $ stc setup
104 2016-12-23 12:26:44 Setup started
105 2016-12-23 12:26:44 Uninstall-3 started -- onos-uninstall 10.128.0.218
106 2016-12-23 12:26:44 Uninstall-2 started -- onos-uninstall 10.128.0.217
107 2016-12-23 12:26:44 Uninstall-1 started -- onos-uninstall 10.128.0.216
108 2016-12-23 12:26:44 Push-Bits-2 started -- onos-push-bits 10.128.0.217
109 2016-12-23 12:26:44 Push-Bits-3 started -- onos-push-bits 10.128.0.218
110 2016-12-23 12:26:44 Push-Bits-1 started -- onos-push-bits 10.128.0.216
111 2016-12-23 12:26:45 Push-Bits-1 completed
112 2016-12-23 12:26:46 Push-Bits-2 completed
113 2016-12-23 12:26:46 Push-Bits-3 completed
114 2016-12-23 12:26:46 Uninstall-3 completed
115 2016-12-23 12:26:46 Kill-3 started -- onos-kill 10.128.0.218
116 2016-12-23 12:26:46 Uninstall-2 completed
117 2016-12-23 12:26:46 Kill-2 started -- onos-kill 10.128.0.217
118 2016-12-23 12:26:46 Uninstall-1 completed
119 2016-12-23 12:26:46 Kill-1 started -- onos-kill 10.128.0.216
120 2016-12-23 12:26:46 Kill-3 completed
121 2016-12-23 12:26:46 Install-3 started -- onos-install 10.128.0.218
122 2016-12-23 12:26:46 Kill-1 completed
123 2016-12-23 12:26:46 Install-1 started -- onos-install 10.128.0.216
124 2016-12-23 12:26:46 Kill-2 completed
125 2016-12-23 12:26:46 Install-2 started -- onos-install 10.128.0.217
126 2016-12-23 12:26:52 Install-2 completed
127 2016-12-23 12:26:52 Secure-SSH-2 started -- onos-secure-ssh -u onos -p rocks 10.128.0.217
128 2016-12-23 12:26:52 Install-1 completed
129 2016-12-23 12:26:52 Secure-SSH-1 started -- onos-secure-ssh -u onos -p rocks 10.128.0.216
130 2016-12-23 12:26:52 Install-3 completed
131 2016-12-23 12:26:52 Secure-SSH-3 started -- onos-secure-ssh -u onos -p rocks 10.128.0.218
132 2016-12-23 12:27:07 Secure-SSH-1 completed
133 2016-12-23 12:27:07 Wait-for-Start-1 started -- onos-wait-for-start 10.128.0.216
134 2016-12-23 12:27:09 Secure-SSH-3 completed
135 2016-12-23 12:27:09 Wait-for-Start-3 started -- onos-wait-for-start 10.128.0.218
136 2016-12-23 12:27:13 Secure-SSH-2 completed
137 2016-12-23 12:27:13 Wait-for-Start-2 started -- onos-wait-for-start 10.128.0.217
138 2016-12-23 12:27:14 Wait-for-Start-1 completed
139 2016-12-23 12:27:14 Check-Components-1 started -- onos-check-components 10.128.0.216
140 2016-12-23 12:27:14 Check-Nodes-1 started -- onos-check-nodes 10.128.0.216
141 2016-12-23 12:27:14 Wait-for-Start-3 completed
142 2016-12-23 12:27:14 Check-Nodes-3 started -- onos-check-nodes 10.128.0.218
143 2016-12-23 12:27:14 Check-Components-3 started -- onos-check-components 10.128.0.218
144 2016-12-23 12:27:16 Wait-for-Start-2 completed
145 2016-12-23 12:27:16 Check-Nodes-2 started -- onos-check-nodes 10.128.0.217
146 2016-12-23 12:27:16 Check-Components-2 started -- onos-check-components 10.128.0.217
147 2016-12-23 12:27:18 Check-Nodes-1 completed
148 2016-12-23 12:27:18 Check-Nodes-3 completed
149 2016-12-23 12:27:19 Check-Nodes-2 completed
150 2016-12-23 12:27:20 Check-Components-1 completed
151 2016-12-23 12:27:20 Check-Apps-1 started -- onos-check-apps 10.128.0.216 drivers,gui,openflow,segmentrouting,fpm,dhcprelay,routeradvertisement,t3,hostprobingprovider includes
152 2016-12-23 12:27:20 Check-Logs-1 started -- onos-check-logs 10.128.0.216
153 2016-12-23 12:27:20 Check-Components-3 completed
154 2016-12-23 12:27:20 Check-Apps-3 started -- onos-check-apps 10.128.0.218 drivers,gui,openflow,segmentrouting,fpm,dhcprelay,routeradvertisement,t3,hostprobingprovider includes
155 2016-12-23 12:27:20 Check-Logs-3 started -- onos-check-logs 10.128.0.218
156 2016-12-23 12:27:20 Check-Apps-1 completed
157 2016-12-23 12:27:20 Check-Apps-3 completed
158 2016-12-23 12:27:20 Check-Logs-1 completed
159 2016-12-23 12:27:20 Check-Logs-3 completed
160 2016-12-23 12:27:21 Check-Components-2 completed
161 2016-12-23 12:27:21 Check-Logs-2 started -- onos-check-logs 10.128.0.217
162 2016-12-23 12:27:21 Check-Apps-2 started -- onos-check-apps 10.128.0.217 drivers,gui,openflow,segmentrouting,fpm,dhcprelay,routeradvertisement,t3,hostprobingprovider includes
163 2016-12-23 12:27:21 Check-Apps-2 completed
164 2016-12-23 12:27:21 Check-Logs-2 completed
165 2016-12-23 12:27:21 Setup completed
166 0:36 Passed! 31 steps succeeded
167
168
169Useful Utilities
170----------------
171- Push network configuration to one particular instance of ONOS (all instances will automatically get the same configuration)
172
173 .. code-block:: console
174
175 $ onos-netcfg $OC1 network-cfg.json
176
177- Remotely log in to CLI of one particular ONOS instance
178
179 .. code-block:: console
180
181 $ onos $OC1
182
183- Remotely access the log of one particular ONOS instance
184
185 .. code-block:: console
186
187 $ onos-log $OC1
188
189
190Install Switch OS - ONL
191=======================
Charles Chan4d5ee192019-09-09 23:08:36 -0700192The switches listed in the :doc:`Supported Hardware <supported-hardware>` are shipped with Open Networking Install Environment (ONIE) boot loader.
Charles Chandd26eeb2019-08-29 17:59:21 -0700193After booting up, we should see the ONIE prompt from console.
194Here we assume that the management port on the switch already has Internet access. (via DHCP)
195
196
197Enter ONIE
198----------
199
200
201Has no ONL or Has ONL 1.x previously installed
202^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203The way to install ONL 2.x is the same as ONL 1.x.
204However, if you have no ONL installed or have older version of ONL, you might find it tricky to (re)install a newer version.
205Here's the instruction:
206
207 1. Plug in the console cable and reboot the switch
208 2. (If your boot loader is grub) When you see the boot menu, select **ONIE -> ONIE: Rescue**
209 3. (If your boot loader is uboot) When you see **Hit any key to stop autoboot** instead of the boot menu,
210 press any key and then enter ``run onie_rescue`` to enter ONIE rescue mode.
211
212Has ONL 2.x previously installed
213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
214It would be much more easier to reboot into ONIE if you have a previously installed ONL 2. Simply run:
215
216
217.. code-block:: console
218
219 # onl-onie-boot-mode rescue
220 # reboot
221
222Available ONIE modes are: *install, rescue, uninstall, update, embed, diag, none*.
223This can be helpful when you are in a normal ONL and want to upgrade your system.
224
225
226Install ONL
227-----------
228At the ONIE prompt, we need to download and install ONL. To fetch and install the latest compatible ONL, run:
229
230.. code-block:: console
231
232 ONIE:/ # wget https://github.com/opencord/OpenNetworkLinux/releases/download/2017-10-19.2200-1211610/ONL-2.0.0_ONL-OS_2017-10-19.2200-1211610_AMD64_INSTALLED_INSTALLER
233 ONIE:/ # sh ONL-2.0.0_ONL-OS_2017-10-19.2200-1211610_AMD64_INSTALLED_INSTALLER
234
235**Checksum**: *sha256:2db316ea83f5dc761b9b11cc8542f153f092f3b49d82ffc0a36a2c41290f5421*
236
237The switch will automatically reboot into ONL after installation. Default login credential of ONL is: ``root/onl``
238
239We might want to configure a fixed IP address for the management interface.
240First edit ``/etc/network/interfaces`` and configure ``ma1``, which is the management interface.
241
242.. code-block:: text
243
244 auto ma1
245 iface ma1 inet static
246 address 10.128.10.128
247 netmask 255.255.0.0
248 gateway 10.128.0.1
249 dns-nameservers 192.168.1.1 8.8.8.8
250
251
252Install Switch Agent - OF-DPA
253=============================
254
Charles Chan64adc382019-09-09 18:15:02 -0700255.. note::
256 **Community vs. Premium Version**
Charles Chandd26eeb2019-08-29 17:59:21 -0700257
Charles Chan64adc382019-09-09 18:15:02 -0700258 The OF-DPA image we distribute for free with Trellis is a community version.
259 This documentation is also written based on the community version.
260 The **community version** has most of the features available and therefore it is **good for small scale deployments** such as lab trials.
261 However, we highly recommend you to get the **premium version** from Broadcom if you are aiming for **production deployments at scale**.
Charles Chandd26eeb2019-08-29 17:59:21 -0700262
263
264Install OF-DPA
265--------------
266We need to use different OF-DPA images depending on the switch model you are using.
267Please find the installer URL corresponding to each switch model in the `Vendor Specific Information`_ section.
268
269Copy the image to the switch and start the installation process by running:
270
271.. code-block:: console
272
273 $ scp ${OFDPA_DEB} ${SWITCH_IP}:/root
274 $ dpkg -i --force-overwrite /root/${OFDPA_DEB}
275
276For example, assuming the OF-DPA image is ``ofdpa_3.0.5.5+accton1.7-1_amd64.deb`` and the switch management IP is ``10.128.0.201``, you should run:
277
278.. code-block:: console
279
280 $ scp ofdpa_3.0.5.5+accton1.7-1_amd64.deb 10.128.0.201:/root
281 $ dpkg -i --force-overwrite /root/ofdpa_3.0.5.5+accton1.7-1_amd64.deb
282
283
284Connect Switch to Controller
285============================
286
Charles Chan19833d82019-09-07 20:49:14 -0700287.. caution::
288 We are going to describe two different ways to start OF-DPA and OpenFlow agent in this section.
289 Some vendors use ``ofagentd`` service while others use old ``launcher`` app to start the agent.
290 Please check the `Vendor Specific Information`_ to understand which method you should use before continuing this section.
Charles Chandd26eeb2019-08-29 17:59:21 -0700291
Charles Chan19833d82019-09-07 20:49:14 -0700292Use ofagentd service
293--------------------
294
295Launch with ofagentd
296^^^^^^^^^^^^^^^^^^^^
Charles Chandd26eeb2019-08-29 17:59:21 -0700297The OFDPA software and the Indigo agent are now a single process launched by Linux service. First of all, we need to configure **/etc/ofagent/ofagent.conf**.
298Uncomment and edit the following line. Make sure all other lines stay commented.
299
300.. code-block:: bash
301
302 OPT_ARGS="-t <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid>"
303
304We can choose to run OF-DPA in **debug mode**
305
306.. code-block:: bash
307
308 OPT_ARGS="-d 2 -c 2 -c 4 -t <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid>"
309
Charles Chan19833d82019-09-07 20:49:14 -0700310- To **start** the ofagent, run ``service ofagentd start``
311- To **stop** the agent, run ``service ofagentd stop``
Charles Chandd26eeb2019-08-29 17:59:21 -0700312- More ``ofagentapp`` options can be found by running ``ofagentapp --help``
313
314
Charles Chan19833d82019-09-07 20:49:14 -0700315Launch in listen mode with ofagentd
316^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Charles Chandd26eeb2019-08-29 17:59:21 -0700317An optional ``-l`` parameter can be added for switch to listen on specific **IP:port**.
318This allows us to use tools like **ovs-ofctl** or **dpctl** to connect and control the switch.
319
320.. code-block:: bash
321
322 OPT_ARGS="-t <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid> -l <ip>:<port>"
323
Charles Chan19833d82019-09-07 20:49:14 -0700324Please refer to `Connect to Switch in Listen Mode`_ to learn more about how to access switches in listen mode.
325
326Use launcher app
327----------------
328
329Launch with launcher
330^^^^^^^^^^^^^^^^^^^^
331- To **start** OF-DPA and OpenFlow agent, run:
332
333 .. code-block:: console
334
335 # ./launcher ofagentapp -t <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid>
336
337- We can choose to run OF-DPA in **debug mode**
338
339 .. code-block:: console
340
341 # ./launcher ofagentapp -d 2 -c 2 -c 4 -t <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid>
342
343- To **stop** OF-DPA and OpenFlow agent, run:
344
345 .. code-block:: consol
346
347 # killall ofagentapp
348
349Launch in listen mode with launcher
350^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
351An optional ``-l`` parameter can be added for switch to listen on specific **IP:port**.
352This allows us to use tools like **ovs-ofctl** or **dpctl** to connect and control the switch.
Charles Chandd26eeb2019-08-29 17:59:21 -0700353
354.. code-block:: console
355
Charles Chan19833d82019-09-07 20:49:14 -0700356 # ./launcher ofagentapp <controller_ip_1> -t <controller_ip_2> -t <controller_ip_3> -i <dpid> -l <ip>:<port>
Charles Chandd26eeb2019-08-29 17:59:21 -0700357
Charles Chan19833d82019-09-07 20:49:14 -0700358Please refer to `Connect to Switch in Listen Mode`_ to learn more about how to access switches in listen mode.
Charles Chandd26eeb2019-08-29 17:59:21 -0700359
360
361Vendor Specific Information
362===========================
363
364
365Edgecore
366--------
367
Charles Chan19833d82019-09-07 20:49:14 -0700368- **OF-DPA Image**
Charles Chandd26eeb2019-08-29 17:59:21 -0700369 - `EdgeCore 5712-54X / 5812-54X / 6712-32X / 7712-32X <https://raw.githubusercontent.com/onfsdn/atrium-docs/master/16A/ONOS/builds/ofdpa_3.0.5.5%2Baccton1.7-1_amd64.deb>`_ - **Checksum**: *sha256:db228b6e79fb15f77497b59689235606b60abc157e72fc3356071bcc8dc4c01f*
370
Charles Chan19833d82019-09-07 20:49:14 -0700371- **Start OF-DPA and OpenFlow agent**
372 - Please refer to `Use ofagentd service`_
373
374- **Configure Port Speed and Breakout**
Charles Chandd26eeb2019-08-29 17:59:21 -0700375 - By default all the switch ports are running at maximum speed. The port speed can be modified in **/etc/accton/ofdpa.conf**
376
377 .. code-block:: text
378
379 port_speed_1=1000 # configure front port 1 to run at 1G
380
381 - We can also configure the same file to use break out cables on certain ports.
382
383 .. code-block:: text
384
385 port_mode_1=4x10g # configure front port 1 to break out from 40G to 4x10G
386
387 OF-DPA service needs to be restarted after modifying this configuration.
388
389
390QCT
391---
392
393- OF-DPA Image
394 - `QuantaMesh T3048-LY8 <https://raw.githubusercontent.com/onfsdn/atrium-docs/master/16A/ONOS/builds/ofdpa-ag7648_0.3.0.5.6_amd64.deb>`_ - **Checksum**: *sha256:f8201530b1452145c1a0956ea1d3c0402c3568d090553d0d7b3c91a79137da9e*
395 - `QuantaMesh T7032-IX1 / IX1B <https://raw.githubusercontent.com/onfsdn/atrium-docs/master/16A/ONOS/builds/ofdpa-ix1_0.3.0.5.0-EA5-qct-01.00_amd64.deb>`_ **Checksum**: *sha256:278b8ffed8a8fc705a1b60d16f8e70377e78342a27a11568a1d80b1efd706a46*
396
Charles Chan19833d82019-09-07 20:49:14 -0700397- **Start OF-DPA and OpenFlow agent**
398 - Please refer to `Use launcher app`_
399
400- Configure Port Speed and Breakout
401 The command ``client_drivshell`` can be used to configure the port speed.
402 Use the parameter ``ps`` to list all ports or ``ps <port number>`` to list one specific port.
403
404 .. code-block:: console
405
406 # client_drivshell ps 1
407 Calling ofdpaBcmCommand rpc with command = "ps 1 ".
408 ena/ speed/ link auto STP lrn inter max loop
409 port link duplex scan neg? state pause discrd ops face frame back
410 xe0( 1) down 10G FD SW No Forward Untag F SFI 9412
411
412 Returned from ofdpaBcmCommand rpc with rc = 0.
413
414 Then use the parameter ``port <port number> sp=<port speed>`` to change the port speed.
415
416 .. code-block:: console
417
418 # client_drivshell port xe0 sp=1000
419 Calling ofdpaBcmCommand rpc with command = "port xe0 sp=1000 ".
420
421 Returned from ofdpaBcmCommand rpc with rc = 0.
422
423 # client_drivshell ps 1
424 Calling ofdpaBcmCommand rpc with command = "ps 1 ".
425 ena/ speed/ link auto STP lrn inter max loop
426 port link duplex scan neg? state pause discrd ops face frame back
427 xe0( 1) down 1G FD SW No Forward Untag F GMII 9412
428
429 Returned from ofdpaBcmCommand rpc with rc = 0.
Charles Chandd26eeb2019-08-29 17:59:21 -0700430
431Delta
432-----
433
434- OF-DPA Image
435 - `Delta AG7648 <https://raw.githubusercontent.com/onfsdn/atrium-docs/master/16A/ONOS/builds/ofdpa-ly8_0.3.0.5.0-EA5-qct-01.01_amd64.deb>`_ - **Checksum**: *sha256:ddfc13cb98ca47291dce5e6938b1d65f0b99bbe77f0585e36ac0007017397f23*
436
Charles Chan19833d82019-09-07 20:49:14 -0700437- **Start OF-DPA and OpenFlow agent**
438 - Please refer to `Use launcher app`_
439
Charles Chandd26eeb2019-08-29 17:59:21 -0700440- Special instructions to install ONL
441 Make sure ``/etc/machine.conf`` looks like the following in ONIE before running ONL installation script:
442
443 .. code-block:: text
444
445 onie_platform=x86_64-delta_<platform name>-r0
446 onie_machine=delta_<platform name>
447
448 After the installation of ONL, if you don't see '/usr/bin' in your PATH variable, please run the following command:
449
450 .. code-block:: console
451
452 # export PATH=$PATH:/usr/bin
453
Charles Chandd26eeb2019-08-29 17:59:21 -0700454
455Useful Information
456==================
457
Charles Chandd26eeb2019-08-29 17:59:21 -0700458OF-DPA Commands
459---------------
460There are some useful OF-DPA commands under ``/usr/bin/``
461
462.. code-block:: text
463
464 client_cfg_purge
465 client_debugcomp
466 client_drivshell
467 client_flowtable_dump
468 client_meter_dump
469 client_port_table_dump
470 client_tunnel_dump
471 client_classcolortable_dump
472 client_debuglvl
473 client_event
474 client_grouptable_dump
475 client_oam_dump
476 client_queue_config
477
478
479ONL Boot Mode
480-------------
481OFDPA offers two boot mode: **INSTALLED** and **SWI**.
482
483- In **INSTALLED** mode, ONL mounts the root filesystem from /dev/sdb7 which is a flash drive that persists everything even during a power cycle.
484- In **SWI** mode, ONL will load the root filesystem from a read-only image (\*.swi) and put the modified files in an copy-on-write overlay filesystem.
485 The change will not be persisted during a power cycle.
486 The pros and cons are obvious. INSTALLED mode is more convenient while SWI mode is more error-safe.
487
488The boot mode will be determined by which image we used install ONL. We use the **INSTALLED** mode in this instruction for simplicity.
489But we can still change it after the installation. Here's the instruction:
490
491.. code-block:: console
492
493 # mount /mnt/onl/boot -o remount,rw
494 # sed -i 's/BOOTMODE=INSTALLED/BOOTMODE=SWI/g' /mnt/onl/boot/boot-config
495 # reboot
496
497
498Persistence Mechanism
499---------------------
500INSTALLED mode already persists everything for you. This section is mainly for SWI mode.
501
502The mechanism to persist files on the switch is different from ONL 1.x to ONL 2.x.
503Following are the steps required to persist a file (e.g. OFDPA package) in ONL 2.x.
504
505- Files put in **/mnt/onl/data** will be persisted automatically.
506- To install a deb package during start-up, put the deb file under **/mnt/onl/data/install-debs** folder and
507 create a plain text file **/mnt/onl/data/install-debs/list** with all the filename of the deb (e.g. ofdpa_3.0.5.5+accton1.7-1_amd64.deb)
508- To execute some command during start-up, put the command in **/mnt/onl/data/rc.boot**
509
510 .. code-block:: bash
511
512 # set static ip and route (dhcp by default)
513 echo 'ip addr add 10.128.0.203/16 dev ma1' >> /mnt/onl/data/rc.boot
514 echo 'ip route add default via 10.128.0.1' >> /mnt/onl/data/rc.boot
515 # grant executable permission
516 chmod a+x /mnt/onl/data/rc.boot
517
518See `PersistWorkflow.md <https://github.com/opencomputeproject/OpenNetworkLinux/blob/master/docs/PersistWorkflow.md>`_ for more detail.
519
520
521Build a Customized ONL Image
522----------------------------
523Sometimes we need to build our own ONL image from source to include some extra files. (The most common case is a modified /etc/network/interfaces).
524The instruction of build process has already been well-documented in ONL repo `Building.md <https://github.com/opencomputeproject/OpenNetworkLinux/blob/master/docs/Building.md>`_.
525But you might find it a little bit tricky to inject some extra files.
526To do that, you need to put the files under **$ONL_ROOT/builds/any/rootfs/jessie/common/overlay/** and then run the make command again.
527
528
529Recovery from a Faulty ONL Install
530----------------------------------
531If, for some reason, the ONL install process fails, you may be brought to the grub rescue prompt upon reboot.
532You may or may not find system files, or even basic grub rescue commands (i.e. 'help').
533There are two options for returning to a (known working) ONIE prompt.
534
5351. **Reinstaller** - You should be able to acquire an ISO image for resetting the firmware to factory default from your switch vendor.
536 Once you have the ISO, you can either use PXE or a live USB to boot the switch into the image.
5372. **Manually boot to ONIE** - If the files are there, you can manually configure GRUB to load the necessary modules to boot back into ONIE.
538
539 .. code-block:: console
540
541 # This should be the partition on the ONIE partition on the AS6712.
542 # It might be hd1 or hd0. Change appropriately.
543 grub rescue> ls (hd0,gpt2)/
544 ./ ../ lost+found/ onie/ grub/ grubenv
545
546 # These instructions will load the kernel and ONIE initrd.
547 grub rescue> set prefix=(hd0,gpt2)/grub
548 grub rescue> set root=(hd0,gpt2)
549 grub rescue> insmod normal
550 grub rescue> insmod linux
551 grub rescue> ls /onie
552 ./ ../ vmlinuz-3.2.35-onie initrd.img-3.2.35-onie tools/ grub/ grub.d/ config/
553
554 # if the ",115200n8" is omitted, baud rate defaults to 9600.
555 grub rescue> linux /onie/vmlinuz-3.2.35-onie console=tty0 console=ttyS1,115200n8
556 grub rescue> initrd /onie/initrd.img-3.2.35-onie
557
558 # The system will not boot into ONIE and you can recover or re-install from there.
559 grub rescue> boot
560
561Once back at the ONIE prompt, you can try to install ONL by following the same steps again.
562
563
Charles Chan19833d82019-09-07 20:49:14 -0700564Connect to Switch in Listen Mode
565--------------------------------
566To connect to the switch in Listen Mode using **ovs-ofctl**, you can use commands such as
567
568.. code-block:: console
569
570 $ ovs-ofctl -O OpenFlow13 show tcp:<ip>:<port>
571 $ ovs-ofctl -O OpenFlow13 dump-flows tcp:<ip>:<port>
572 $ ovs-ofctl -O OpenFlow13 dump-groups tcp:<ip>:<port>
573 $ ovs-ofctl -O OpenFlow13 add-flow tcp:<ip>:<port> table=60,priority=40000,eth_type=0x0800,ip_dst=55.55.55.55,actions=controller
574
575For more command, please see ``ovs-ofctl --help`` or the post `OpenvSwitch ovs-ofctl and OF-DPA <https://blog.pichuang.com.tw/20170106-ovs-ofctl-and-ofdpa/>`_.
576
577
Charles Chandd26eeb2019-08-29 17:59:21 -0700578Reference
579---------
580- `ONL/OF-DPA installation guide by Edgecore Networks <https://www.youtube.com/watch?v=mCUtkIc_hVI>`_
581- `ONL/OF-DPA cheat sheet by Phil Huang <https://blog.pichuang.com.tw/20170104-ofdpa-with-onl-cheat-sheet/>`_