near-rt-ric-simulator/README.md

   1 # O-RAN-SC Near-RealTime RIC Simulator
   2
   3 The O-RAN SC Near-RealTime RIC simulates the A1 as an generic REST API which can receive and send northbound messages. The simulator validates the payload and applies policy.
   4
   5 The simulator supports multiple A1 interface versions (version of the open API yaml file\):
   6 | Yaml file version     | Version id|
   7 | --------------------- | ------------------- |
   8 | OSC 2.1.0,            |      OSC\_2.1.0     |
   9 | A1 Standard 1.1.3,    |      STD\_1.1.3     |
  10 | 1.1.x-alpha.2 ,       |      1.1.x-alpha.2  |
  11
  12 All versions are supported by the same container, see section 'Configuring the simulator' below for details about how to the start the simulator with the intended version id.
  13
  14 The overall folder structure is \(relative to the location of this README file\):
  15 | Dir              | Description |
  16 | ---------------- | ----------- |
  17 |.                 |Dockerfile and README |
  18 |api               |The open api yaml for each supported version |
  19 |src               |Python source code for each supported version |
  20 |test              |Basic test |
  21 |certificate       |A self-signed certificate and a key
  22
  23 The simulator handles the requests that are defined in the A1 open API yaml file. All these requests are implemented in the a1.py file in the source folder. In addition, a number of administrative functions are also supported and implemented by the main.py in the source folder.
  24
  25 The section below outlines the supported open api REST operations as well as the adminstrative REST operations. For the
  26 documentation of the common parts in the admin API, see [Common Functions](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#common-functions).
  27
  28 # Ports and certificates
  29
  30 The simulator normally opens the port 8085 for http. If a certificate and a key are provided the simulator will open port 8185 for https instead. The port 8185 is only opened if a valid certificate and key is found.
  31 The certificate and key shall be placed in the same dir and the dir shall be mounted to /usr/src/app/cert in the container.
  32
  33 | Port     | Protocol |
  34 | -------- | ----- |
  35 | 8085     | http  |
  36 | 8185     | https |
  37
  38 The dir certificate contains a self-signed cert. Use the script generate_cert_and_key.sh to generate a new certificate and key. The password of the certificate must be set 'test'.
  39 The same urls are availables on both the http port 8085 and the https port 8185. If using curl and https, the flag -k shall be given to make curl ignore checking the certificate.
  40
  41 # Supported operations in simulator OSC 2.1.0
  42
  43 For the complete yaml specification, see [openapi.yaml](../near-rt-ric-simulator/api/OSC_2.1.0/openapi.yaml).
  44
  45 URIs for A1:
  46 | Function              | Path and parameters |
  47 | --------------------- | ------------------- |
  48 |  GET, do a healthcheck |  http://localhost:8085/a1-p/healthcheck |
  49 |  GET, get all policy type ids | http://localhost:8085/a1-p/policytypes |
  50 |  DELETE, delete a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  51 |  GET, get a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  52 |  PUT, create/update a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  53 |  GET, get all policy ids for a type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies |
  54 |  DELETE, delete a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  55 |  GET, get a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  56 |  PUT, create/update a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  57 |  GET, get policy status | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id}/status |
  58
  59 Swagger UI at: http://localhost:8085/ui/
  60
  61 For the documentation of the admin API, see [OSC_2.1.0](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#osc-2-1-0).
  62
  63 URIs for admin operations:
  64 | Function              | Path and parameters |
  65 | --------------------- | ------------------- |
  66 |  GET, a basic healthcheck | http://localhost:8085/ |
  67 |  GET, a list of all supported interfaces | http://localhost:8085/container\_interfaces |
  68 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
  69 |  POST, full reset | http://localhost:8085/deleteall |
  70 |  PUT, create/update a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  71 |  DELETE, delete a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  72 |  GET, list of policy type id | http://localhost:8085/policytypes |
  73 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
  74 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
  75 |  PUT, set status and optional reason, delete and timestamp | http://localhost:8085/status?status=&lt;status&gt;&amp;reason=&lt;reason&gt;[&amp;deleted=&lt;boolean&gt;][&amp;created\_at=&lt;timestamp&gt;]  |
  76 |  GET a counter  <br> (counter-name: 'num\_instances', 'num\_types', 'interface' or 'remote\_hosts') | http://localhost:8085/counter/&lt;counter-name&gt; |
  77
  78
  79 # Supported operations in simulator A1 Standard 1.1.3
  80
  81 For the complete yaml specification, see [STD_A1.yaml](../near-rt-ric-simulator/api/STD_1.1.3/STD_A1.yaml).
  82
  83 URIs for A1:
  84 | Function              | Path and parameters |
  85 | --------------------- | ------------------- |
  86 |  GET all policy identities | http://localhost:8085/A1-P/v1/policies |
  87 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v1/policies/{policyId} |
  88 |  GET a policy | http://localhost:8085/A1-P/v1/policies/{policyId} |
  89 |  DELETE a policy instance | http://localhost:8085/A1-P/v1/policies/{policyId} |
  90 |  GET a policy status | http://localhost:8085/A1-P/v1/policies/{policyid} |
  91 Swagger UI at: http://localhost:8085/A1-P/v1/ui/
  92
  93 For the documentation of the admin API, see [A1 Standard 1.1.3](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#a1-standard-1-1-3).
  94
  95 URIs for admin operations:
  96 | Function              | Path and parameters |
  97 | --------------------- | ------------------- |
  98 |  GET, a basic healthcheck | http://localhost:8085/ |
  99 |  GET, a list of all supported interfaces | http://localhost:8085/container\_interfaces |
 100 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
 101 |  POST, full reset | http://localhost:8085/deleteall |
 102 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
 103 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
 104 |  PUT, set status and optional reason | http://localhost:8085/status?status=&lt;status&gt;[&amp;reason=&lt;reason&gt;] |
 105 |  POST, send status for policy | http://localhost:8085/sendstatus?policyid=&lt;policyid&gt; |
 106 |  GET a counter <br> (counter-name: 'num\_instances', 'num\_types'(always 0), 'interface' or 'remote\_hosts') | http://localhost:8085/counter/&lt;counter-name&gt; |
 107
 108
 109
 110 # Supported operations in simulator 1.1.x-alpha.2
 111
 112 For the complete yaml specification, see [a1-openapi.yaml](../near-rt-ric-simulator/api/1.1.x-alpha.2/a1-openapi.yaml).
 113
 114 The available requests and the addresses are currently:
 115 | Function              | Path and parameters |
 116 | --------------------- | ------------------- |
 117 |  GET all policy identities (respectively for a policy type if query parameter used) | http://localhost:8085/A1-P/v1/policies?policyTypeId={policyTypeId} |
 118 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v1/policies/{policyId}?policyTypeId={policyTypeId} |
 119 |  GET a policy | http://localhost:8085/A1-P/v1/policies/{policyId} |
 120 |  DELETE a policy instance | http://localhost:8085/A1-P/v1/policies/{policyId} |
 121 |  GET a policy status | http://localhost:8085/A1-P/v1/policystatus |
 122 |  GET all policy types | http://localhost:8085/A1-P/v1/policytypes |
 123 |  GET the schemas for a policy type | http://localhost:8085/A1-P/v1/policytypes/{policyTypeId} |
 124
 125 Nota Bene: It could happen that this page is not updated as soon as the yaml file is. The yaml file can be found under /near-rt-ric-simulator/a1-openapi.yaml.
 126
 127 For the documentation of the admin API, see [1.1.x-alpha.2](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#x-alpha-2).
 128
 129 Additionally, there are requests that are defined in main.py as an administrative API. The goal is to handle information that couldn't be handled using the A1 interface. The available requests and the addresses are currently:
 130 | Function              | Path and parameters |
 131 | --------------------- | ------------------- |
 132 |  GET, a basic healthcheck | http://localhost:8085/ |
 133 |  PUT a policy type | http://localhost:8085/policytypes/{policyTypeId} |
 134 |  DELETE a policy type | http://localhost:8085/policytypes/{policyTypeId} |
 135 |  DELETE all policy instances | http://localhost:8085/deleteinstances |
 136 |  DELETE all policy types | http://localhost:8085/deletetypes |
 137 |  PUT a status to a policy instance with an enforceStatus parameter only | http://localhost:8085/{policyId}/{enforceStatus} |
 138 |  PUT a status to a policy instance with both enforceStatus and enforceReason | http://localhost:8085/{policyId}/{enforceStatus}/{enforceReason} |
 139 |  GET a counter  <br> (counter-name: 'num\_instances', 'num\_types', 'interface' or 'remote\_hosts') | http://localhost:8085/counter/{counter-name} |
 140
 141 The backend server publishes live API documentation at the URL `http://localhost:8085/A1-P/v1/ui/`
 142
 143 # Configuring the simulator
 144 An env variable, A1\_VERSION need to be passed to the container at start to select the desired interface version. The variable shall be set to one of the version-ids shown in the table in the first section. For example A1\_VERSIION=STD\_1.1.3.
 145 An env variable, REMOTE_HOSTS_LOGGING, can be set (any value is ok) and the the counter remote\_hosts will log the host names of all remote hosts that has accessed the A1 URIs. If host names cannot be resolved, the ip address of the remote host is logged instead. This logging is default off so must be configured to be enabled. If not configured, the counter remote\_hosts will return a fixed text indicating that host name logging is not enabled. Use this feature with caution, remote host lookup may take time in certain environments.
 146 The simulator can also run using the https protocol. The enable https, a valid certificate and key need to provided. There is self-signed certificate available in the certificate dir and that dir shall be mounted to the container to make it available
 147
 148 By default, this image has default certificates under /usr/src/app/cert
 149 file "cert.crt" is the certificate file
 150 file "key.crt" is the key file
 151 file "generate_cert_and_key.sh" is a shell script to generate certificate and key
 152 file "pass" stores the password when you run the shell script
 153
 154 Start the a1-interface container without specifing external certificates:
 155 'docker run -it -p 8085:8085 -p 8185:8185 -e A1\_VERSION=STD\_1.1.3 -e REMOTE_HOSTS_LOGGING=1 a1test'
 156
 157 It will listen to http 8085 port and https 8185 port(using default certificates) at the same time.
 158
 159 This certificates/key can be overriden by mounting a volume when using "docker run" or "docker-compose"
 160 In 'docker run', use field:
 161 --volume "$PWD/certificate:/usr/src/app/cert" a1test
 162 In 'docker-compose.yml', use field:
 163 volumes:
 164       - ./certificate:/usr/src/app/cert:ro
 165
 166 In docker run the full command could look like this:<br> 'docker run -it -p 8085:8085 -p 8185:8185 -e A1\_VERSION=STD\_1.1.3 -e REMOTE_HOSTS_LOGGING=1 --volume /PATH_TO_CERT_DIR/certificate:/usr/src/app/cert a1test'
 167 http port 8085 and https port 8185
 168 The variable for A1 version is set with the '-e' flag.
 169 With logging of remote host enabled "-e REMOTE_HOSTS_LOGGING=1 "
 170 With certificate dir mounted  "--volume /PATH_TO_CERT_DIR/certificate:/usr/src/app/cert"
 171
 172 # Updating the openapi specs
 173 The openapi specifications are stored in the 'api/&lt;version&gt;/'. If adding/replacing with a new file, make sure to copy the 'operationId' parameter for each operation to the new file.
 174
 175 # Start and test of the simulator
 176 First, download the sim/a1-interface repo on gerrit:
 177 git clone "https://gerrit.o-ran-sc.org/oransc/sim/a1-interface"
 178
 179 Goto the main directory, 'a1-interface/near-rt-ric-simulator'.
 180 There is a folder 'test/&lt;version&gt;/' for each supported simulator version. This folder contains a script to build and start the simulator (as a container in interactive mode), a script for basic testing as well as json files for the test script.
 181
 182 Go to the test folder of the selected version, 'test/&lt;version&gt;/.
 183
 184 Note that test can be performed both using the nonsecure http port and the secure https port.
 185
 186 Build and start the simulator container using: ./build\_and\_start.sh
 187 This will build and start the container in interactive mode. The built container only resides in the local docker repository.
 188 Note, the default port is 8085 for http and 8185 for https. When running the simulator as a container, the defualt ports can be re-mapped to any port on the localhost.
 189
 190 In a second terminal, go to the same folder and run the basic test script, basic\_test.sh nonsecure|secure or commands.sh nonsecure|secure depending on version.
 191 This script runs a number of tests towards the simulator to make sure it works properply.
 192
 193 Only for version 1.1.x-alpha.2
 194 Let the simulator run in one terminal; in another terminal, one can run the command ./commands.sh nonsecure|secure. It contains the main requests, and will eventually leave the user with a policy type STD\_QoSNudging\_0.2.0 and a policy instance pi1 with an enforceStatus set to NOT\_ENFORCED and an enforce Reason set to 300.
 195 All the response codes should be 20X, otherwise something went wrong.
 196
 197 ## License
 198
 199 Copyright (C) 2019 Nordix Foundation.
 200 Licensed under the Apache License, Version 2.0 (the "License")
 201 you may not use this file except in compliance with the License.
 202 You may obtain a copy of the License at
 203
 204       http://www.apache.org/licenses/LICENSE-2.0
 205
 206 Unless required by applicable law or agreed to in writing, software
 207 distributed under the License is distributed on an "AS IS" BASIS,
 208 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 209 See the License for the specific language governing permissions and
 210 limitations under the License.
 211
 212 For more information about license please see the [LICENSE](LICENSE.txt) file for details.