blob: 8eec878f00f91509ddf762b479298334385754cb [file] [log] [blame]
.. BBSim documentation master file, created by
sphinx-quickstart on Fri Oct 25 12:03:42 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to BBSim's documentation!
=================================
.. toctree::
:maxdepth: 2
:caption: Contents:
operations.rst
onu-state-machine.rst
olt-state-machine.rst
development-dependencies.rst
bbr.rst
bbsimctl.rst
api.rst
Quickstart
----------
BBSim (a.k.a. BroadBand Simulator) is a tool designed to emulate an `Openolt
<https://github.com/opencord/openolt>`_ compatible device.
In order to use BBSim you need to have:
- a Kubernetes cluster
- helm
- a working installation of VOLTHA
We strongly recommend the utilization of `kind-voltha
<https://github.com/ciena/kind-voltha>`_ to setup such environment.
Installation
------------
Once VOLTHA is up and running, you can deploy BBSim with this command:
.. code:: bash
helm install -n bbsim cord/bbsim
If you need to specify a custom image for BBSim you can:
.. code:: bash
helm install -n bbsim cord/bbsim --set images.bbsim.repository=bbsim --set images.bbsim.tag=candidate --set images.bbsim.pullPolicy=Never
The BBSim installation can be customized to emulate multiple ONUs and multiple
PON Ports:
.. code:: bash
helm install -n bbsim cord/bbsim --set onu=8 --set pon=2
BBSim can also be configured to automatically start Authentication or DHCP:
.. code:: bash
helm install -n bbsim cord/bbsim --set auth=true --set dhcp=true
Once BBSim is installed you can verify that it's running with:
.. code:: bash
kubectl logs -n voltha -f $(kubectl get pods -n voltha | grep bbsim | awk '{print $1}')
Provision a BBSim OLT in VOLTHA
-------------------------------
Create the device:
.. code:: bash
voltctl device create -t openolt -H $(kubectl get -n voltha service/bbsim -o go-template='{{.spec.clusterIP}}'):50060
Enable the device:
.. code:: bash
voltctl device enable $(voltctl device list --filter Type~openolt -q)
BBSim startup options
---------------------
``BBSim`` supports a series of options that can be set at startup, you can see
the list via ``./bbsim --help``
.. code:: bash
$ ./bbsim --help
Usage of ./bbsim:
-auth
Set this flag if you want authentication to start automatically
-c_tag int
C-Tag starting value, each ONU will get a sequential one (targeting 1024 ONUs per BBSim instance the range is big enough) (default 900)
-cpuprofile string
write cpu profile to file
-delay int
The delay between ONU DISCOVERY batches in milliseconds (1 ONU per each PON PORT at a time (default 200)
-dhcp
Set this flag if you want DHCP to start automatically
-logCaller
Whether to print the caller filename or not
-logLevel string
Set the log level (trace, debug, info, warn, error) (default "debug")
-nni int
Number of NNI ports per OLT device to be emulated (default 1)
-olt_id int
Number of OLT devices to be emulated
-onu int
Number of ONU devices per PON port to be emulated (default 1)
-pon int
Number of PON ports per OLT device to be emulated (default 1)
-s_tag int
S-Tag value (default 900)
-enableEvents
Set this flag for publishing BBSim events on configured kafkaAddress
-kafkaAddress string
IP:Port for kafka, used only when bbsimEvents flag is set (default ":9092")
-ca string
Set the mode for controlled activation of PON ports and ONUs
-enableperf bool
Setting this flag will cause BBSim to not store data like traffic schedulers, flows of ONUs etc
``BBSim`` also looks for a configuration file in ``configs/bbsim.yaml`` from
which it reads a number of default settings. The command line options listed
above override the corresponding configuration file settings. A sample
configuration file is given below:
.. literalinclude:: ../../configs/bbsim.yaml
Using the BBSim Sadis server in ONOS
------------------------------------
BBSim provides a simple server for testing with the ONOS Sadis app. The server
listens on port 50074 by default and provides the endpoints
``subscribers/<id>`` and ``bandwidthprofiles/<id>``.
To configure ONOS to use the BBSim ``Sadis`` server endpoints, the Sadis app
must use be configured as follows (see ``examples/sadis-in-bbsim.json``):
.. literalinclude:: ../../examples/sadis-in-bbsim2.json
This base configuration may also be obtained directly from the BBSim Sadis
server:
.. code:: bash
curl http://<BBSIM_IP>:50074/cfg -o examples/sadis.json
It can then be pushed to the Sadis app using the following command:
.. code:: bash
curl -sSL --user karaf:karaf \
-X POST \
-H Content-Type:application/json \
http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis \
--data @examples/sadis-in-bbsim.json
You can verify the current Sadis configuration:
.. code:: bash
curl --user karaf:karaf http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis
In ONOS subscriber information can be queried using ``sadis <id>``.
*Note that BBSim supports both sadis configuration versions, here is an example of the configuration needed to return
the old format:*
.. literalinclude:: ../../examples/sadis-in-bbsim.json
Controlled PON and ONU activation
---------------------------------
BBSim provides support for controlled PON and ONU activation. By default both PON ports and ONUs are automatically activated when OLT is enabled.
This can be controlled using ``-ca`` option.
``-ca`` can be set to one of below four modes:
- default: PON ports and ONUs are automatic activated (default behavior).
- only-onu: PON ports automatically enabled and ONUs dynamically activated
On Enable OLT, IntfIndications for all PON ports are sent but ONU discovery indications are not sent.
When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
- only-pon: PON ports dynamically enabled and ONUs automatically activated
On Enable OLT, neither IntfIndications for PON ports nor ONU discovery indications are sent.
When EnablePonIf request is received at OpenOLT server, then that PON port is enabled and
IntfIndication is sent for that PON and all ONUs under that ports are discovered automatically.
- both: Both PON ports and ONUs are dynamically activated
On Enable OLT, neither IntfIndication for PON ports nor ONU discovery indications are sent.
When EnablePonIf request is received on OpenOLT server then IntfIndication is sent for that PON but no ONU discovery indication will be sent.
When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
Publishing BBSim Events on kafka
--------------------------------
BBSim provides option for publishing events on kafka. To publish events on kafka, set BBSimEvents flag and configure kafkaAddress.
Once BBSim is started, it will publish events (as and when they happen) on topic ``BBSim-OLT-<id>-Events``.
Types of Events:
- OLT-enable-received
- OLT-disable-received
- OLT-reboot-received
- OLT-reenable-received
- ONU-discovery-indication-sent
- ONU-activate-indication-received
- MIB-upload-received
- MIB-upload-done
- Flow-add-received
- Flow-remove-received
- ONU-authentication-done
- ONU-DHCP-ACK-received
Sample output of kafkacat consumer for BBSim with OLT-ID 4:
.. code:: bash
$ kafkacat -b localhost:9092 -t BBSim-OLT-4-Events -C
{"EventType":"OLT-enable-received","OnuSerial":"","OltID":4,"IntfID":-1,"OnuID":-1,"EpochTime":1583152243144,"Timestamp":"2020-03-02 12:30:43.144449453"}
{"EventType":"ONU-discovery-indication-sent","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":0,"EpochTime":1583152243227,"Timestamp":"2020-03-02 12:30:43.227183506"}
{"EventType":"ONU-activate-indication-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243248,"Timestamp":"2020-03-02 12:30:43.248225467"}
{"EventType":"MIB-upload-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243299,"Timestamp":"2020-03-02 12:30:43.299480183"}