Simulated O-RUs according to conf spec
[oam.git] / solution / README.md
1 # Service Management and Orchestration (SMO)
2
3 This project focus on a docker-compose deployment solution for SMO/OAM Components.
4
5 ## Introduction
6
7 With respect to OAM the SMO implements the O1-interface consumers.
8 According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification,
9 the SMO implements a NETCONF Client for configuration and a HTTP/REST/VES server
10 for receiving all kind of events in VES format.
11
12 The setup contains an OpenDaylight based NETCONF client and an ONAP VES Collector.
13
14 ## SMO OAM Components
15
16 This docker-compose file starts a pre-configured, self-contained SDN-R solution
17 with the following components.
18
19   * **Identity**
20     ... representing an KeyCloak based identity service for centralized user
21     management. Please note that the implementation does not support IPv6.
22     Therefore, its own network is required called 'DMZ'.
23
24   * **Controller** single node instance
25
26     ... representing the NETCONF consumer on the Service Management and
27     Orchestration framework (SMO) for O-RAN O1 interface and/or O-RAN OpenFronthaul Management Plane and/or other NETCONF/YANG schemas implemented by the OpenDaylight project.
28
29   * **VES collector**
30
31     ... representing the VES (REST) provider at SMO for all kind of events.
32
33   * **Messages**
34     ... representing SMO MessageRouter component, includes message-router
35
36 ## Prerequisites
37
38 ### Operating (HOST) System
39
40 ```
41 $ cat /etc/os-release | grep PRETTY_NAME
42 PRETTY_NAME="Ubuntu 22.04.2 LTS"
43 ```
44
45 ### Docker
46
47 ```
48 $ docker --version
49 Docker version 23.0.1, build a5ee5b1
50 ```
51 Please follow the required docker daemon configuration as documented in the following README.md:
52 - [./smo/common/docker/README.md](./smo/common/docker/README.md)
53
54 ### Docker Compose
55
56 ```
57 $ docker compose version
58 Docker Compose version v2.17.2
59 ```
60
61 ### GIT
62
63 ```
64 $ git --version
65 git version 2.34.1
66 ```
67
68 ### Python
69
70 ```
71 $ python3 --version
72 Python 3.10.6
73 ```
74
75 A python parser package is required.
76 ```
77 sudo apt install python3-pip
78 pip install jproperties
79 ```
80
81 It is beneficial (but not mandatory) adding the following line add the
82 end of your ~/.bashrc file. I will suppress warnings when python script
83 do not verify self signed certificates for HTTPS communication.
84
85 ```
86 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
87 ```
88
89 ### ETC Host (DNS function)
90
91 Please modify the /etc/hosts of your system.
92
93 * \<your-system>: is the hostname of the system, where the browser is started
94
95 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
96
97 For development purposes <your-system> and <deployment-system> may reference the same system.
98
99 ```
100 $ cat /etc/hosts
101 127.0.0.1                      localhost
102 127.0.1.1                      <your-system>
103
104 # SMO OAM development system
105 <deployment-system-ipv4>                   smo.o-ran-sc.org
106 <deployment-system-ipv4>           gateway.smo.o-ran-sc.org
107 <deployment-system-ipv4>          identity.smo.o-ran-sc.org
108 <deployment-system-ipv4>          messages.smo.o-ran-sc.org
109 <deployment-system-ipv4> ves-collector.oam.smo.o-ran-sc.org
110 <deployment-system-ipv4>         odlux.oam.smo.o-ran-sc.org
111 <deployment-system-ipv4>    controller.oam.smo.o-ran-sc.org
112
113 ```
114
115 ## Expected Folder Structure
116
117 The following figure show the expected folder structure for the different
118 docker-compose file and its configurations.
119
120 ```
121 ├── network
122 │   ├── .env
123 │   ├── config.py
124 │   ├── docker-compose.yml
125 │   │
126 │   ├── ntsim-ng-o-du
127 │   └── ntsim-ng-o-ru
128 └── smo
129     ├── apps
130     │   ├── .env
131     │   ├── docker-compose.yml
132     │   └── flows
133     ├── common
134     │   ├── .env
135     │   ├── docker-compose.yml
136     │   │
137     │   ├── docker
138     │   ├── gateway
139     │   ├── identity
140     │   ├── messages
141     │   ├── kafka
142     │   └── zookeeper
143     └── oam
144         ├── .env
145         ├── docker-compose.yml
146         │
147         ├── odlux
148         ├── controller
149         └── ves-collector
150 ```
151
152 ## Usage
153
154 ### Bring Up Solution
155
156 #### Short story
157
158 The following commands should be invoked. More detailed can be found in the
159 next chapters.
160
161 ```
162 docker compose -f smo/common/docker-compose.yml up -d
163 # wait until the cpu load is low again
164 python smo/common/identity/config.py
165
166 docker compose -f smo/oam/docker-compose.yml up -d
167 docker compose -f smo/apps/docker-compose.yml up -d
168
169 # wait until the cpu load is low again
170
171 docker compose -f network/docker-compose.yml up -d
172 # wait about 2min
173 docker restart ntsim-ng-o-du-1122
174 python network/config.py
175 ```
176
177 #### Check (adjust if required) environment variables
178
179 ```
180 nano smo/common/.env
181 nano smo/oam/.env
182 nano network/.env
183 ```
184
185 #### Startup solution
186
187 Please note that it is necessary to configure first the identity service,
188 before starting further docker images.
189
190 The several docker-compose yml files must be started in the right order as listed below:
191
192 ```
193 docker compose -f smo/common/docker-compose.yml up -d
194 python smo/common/identity/config.py
195 ```
196
197 The python script configure the users within the identity service (keycloak).
198 A system user (%USER) is also created with administration rights.
199
200
201 ```
202 docker compose -f smo/oam/docker-compose.yml up -d
203 ```
204
205 Looking into the ONAP SDN-R logs will give you the startup procedure.
206
207 ```
208 docker logs -f controller
209 ```
210
211 If you see the login page (https://odlux.oam.smo.o-ran-sc.org) you are good to go and can start the (simulated) network.
212
213 ```
214 docker compose -f network/docker-compose.yml up -d
215 ```
216
217 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
218
219 ```
220 docker compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
221 python network/config.py
222 ```
223
224 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
225
226 O-DU - NETCONF Call HOME and NETCONF notifications
227 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
228
229 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
230
231 'True' indicated that the settings through SDN-R to the NETCONF server were
232 successful.
233
234 SDN-R reads the fault events from DMaaP and processes them.
235 Finally the fault events are visible in ODLUX.
236
237 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
238
239
240 ### Log files and karaf console
241
242 #### ODL karaf.logs
243
244 ```
245 docker exec -it controller tail -f /opt/opendaylight/data/log/karaf.log
246 ```
247
248 #### ves-collector logs
249
250 ```
251 docker logs -f ves-collector
252 ```
253
254 ### Customizing Solution
255
256 '.env' file contains customizing parameters
257
258 ### Verification Solution
259
260 #### Access to SDN-R ODLUX
261
262 ##### Login into SDN-R
263
264     https://odlux.oam.smo.o-ran-sc.org
265
266     User: admin // see .env file
267
268     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
269
270 In case of trouble, please update the commands with your customized '.env' file.
271
272 ### Terminate solution
273
274 To stop all container please respect the following order
275
276 ```
277 docker compose -f network/docker-compose.yml down
278 docker compose -f smo/apps/docker-compose.yml down
279 docker compose -f smo/oam/docker-compose.yml down
280 docker compose -f smo/common/docker-compose.yml down
281 ```
282
283 ### Cleanup
284
285 !!! be careful if other stopped containers are on the same system
286 ```
287 docker system prune -a -f
288 ```
289 ### Troubleshooting
290
291 In most cases the .env setting do not fit to the environment and need to be
292 adjusted.
293
294 Please make sure that the network settings to not overlap with other networks.
295
296 The commands ...
297 ```
298 docker ps -a
299 docker-compose ps
300 docker rm -f $(docker ps -aq)