Change in osmo-cbc[master]: manual: Document ECBE; include JSON schema; cross-references

historical

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-cbc/+/22405 )

Change subject: manual: Document ECBE; include JSON schema; cross-references
......................................................................

manual: Document ECBE; include JSON schema; cross-references

Change-Id: I358f72331aa9832cc56c67396eb41b62307a3258
---
M doc/manuals/chapters/configuration.adoc
A doc/manuals/chapters/ecbe-rest-interface.adoc
M doc/manuals/chapters/overview.adoc
M doc/manuals/osmocbc-usermanual.adoc
4 files changed, 62 insertions(+), 22 deletions(-)

Approvals:
  Jenkins Builder: Verified
  laforge: Looks good to me, approved

diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
index 095aed5..5abb3a8 100644
--- a/doc/manuals/chapters/configuration.adoc
+++ b/doc/manuals/chapters/configuration.adoc
@@ -8,6 +8,7 @@
 subsequently distributes it among the (matching) cells within the BSC
 coverage area.
 
+[[config-cbsp]]
 ==== Configuring the CBSP connections
 
 According to 3GPP TS 48.049, a BSC typically operates as a TCP server,
@@ -63,6 +64,7 @@
   local-port 48049
 ----
 
+[[config-ecbe]]
 === ECBE (REST Interface) Configuration
 
 ==== Configuring the IP/Port for ECBE to bind to
diff --git a/doc/manuals/chapters/ecbe-rest-interface.adoc b/doc/manuals/chapters/ecbe-rest-interface.adoc
new file mode 100644
index 0000000..2c03880
--- /dev/null
+++ b/doc/manuals/chapters/ecbe-rest-interface.adoc
@@ -0,0 +1,49 @@
+[[ecbe]]
+== ECBE REST interface
+
+The ECBE (External Cell Broadcast Entity) REST interface is specified in
+the JSON schema files `cbc.schema.json` and `smscb.schema.json`, which
+are part of the OsmoCBC distribution.
+
+The REST interface binds to the IP and TCP port as configured and
+can be reached at `http://IP:PORT/api/ecbe/v1`
+
+NOTE:: It is your responsibility to properly secure access to the REST
+interface endpoint to ensure only legitimate users can access it.  This
+may be achieved via packet filtering and a reverse HTTP proxy.
+
+=== API endpoints
+
+==== `POST /api/ecbe/v1/message`
+
+This command is used to create a new SMSCB or ETWS message inside the CBC.
+The `cbc_messsage` type as specified in the JSON schema (<<ecbe-json>>).
+
+==== `DELETE /api/ecbe/v1/message/:message_id`
+
+This command is used to delete an existing SMSCB or ETWS message from the CBC.
+
+The `:message_id` parameter is the decimal integer representation of the
+cbc_message.smscb.message_id that was specified when creating the
+message via the POST command stated above.
+
+[[ecbe-json]]
+=== JSON Schema
+
+==== `cbc.schema.json`
+
+This is the main JSOM schema for osmo-cbc.  In many places, it
+references `smscb.schema.json` described further below.
+
+----
+include::{srcdir}/../../cbc.schema.json[]
+----
+
+==== `smscb.schema.json`
+
+This JSON schema describes a lot of the basic data types relevant for
+SMSCB. It is used heavily by `cbc.schema.json` described above.
+
+----
+include::{srcdir}/../../smscb.schema.json[]
+----
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
index 2077878..3063ff7 100644
--- a/doc/manuals/chapters/overview.adoc
+++ b/doc/manuals/chapters/overview.adoc
@@ -49,29 +49,16 @@
 the CBC doesn't need to know each and every BSC in the network.  It
 simply only accepts incoming CBSP connections.
 
+For more information, see <<config-cbsp>> on how CBSP is configured.
 
-=== REST interface
+=== ECBE REST interface
 
-The REST interface is specified in the JSON schema files
-`cbc.schema.json` and `smscb.schema.json`, which are part of the OsmoCBC
-distribution.
+3GPP does not specify the external interface by which competent
+authorities can submit SMSCB and/or ETWS messages to a CBC.
 
-The REST interface currently binds to TCP port 12345 (on INADRR_ANY) and
-can be reached at http://localhost:1234/api/ecbe/v1"
+Hence, a non-standard, Osmocom specific  HTTP/REST/JSON based interface
+is offered for external entities to create and delete SMSCB and ETWS
+messages within the CBC.  This interface is called ECBE.
 
-NOTE:: It is your responsibility to properly secure access to the REST
-interface endpoint to ensure only legitimate users can access it.  This
-may be achieved via packet filtering and a reverse HTTP proxy.
-
-==== POST /api/ecbe/v1/message
-
-This command is used to create a new SMSCB or ETWS message inside the CBC.
-The `cbc_messsage` type as specified in the JSON schema.
-
-==== DELETE /api/ecbe/v1/message/:message_id
-
-This command is used to delete an existing SMSCB or ETWS message from the CBC.
-
-The `:message_id` parameter is the decimal integer representation of the
-cbc_message.smscb.message_id that was specified when creating the
-message via the POST command stated above.
+For more information, see <<ecbe>> on the ECBE API definition and <<config-ecbe>>
+on how it is configured.
diff --git a/doc/manuals/osmocbc-usermanual.adoc b/doc/manuals/osmocbc-usermanual.adoc
index 967ec96..e08586d 100644
--- a/doc/manuals/osmocbc-usermanual.adoc
+++ b/doc/manuals/osmocbc-usermanual.adoc
@@ -16,6 +16,8 @@
 
 include::{srcdir}/chapters/introspection.adoc[]
 
+include::{srcdir}/chapters/ecbe-rest-interface.adoc[]
+
 include::./common/chapters/counters-overview.adoc[]
 
 include::{srcdir}/chapters/counters.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-cbc/+/22405
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-cbc
Gerrit-Branch: master
Gerrit-Change-Id: I358f72331aa9832cc56c67396eb41b62307a3258
Gerrit-Change-Number: 22405
Gerrit-PatchSet: 6
Gerrit-Owner: laforge <laforge at osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge at osmocom.org>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20210124/5df8c1ea/attachment.htm>
