<p>laforge <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-cbc/+/22405">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Jenkins Builder: Verified
laforge: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">manual: Document ECBE; include JSON schema; cross-references<br><br>Change-Id: I358f72331aa9832cc56c67396eb41b62307a3258<br>---<br>M doc/manuals/chapters/configuration.adoc<br>A doc/manuals/chapters/ecbe-rest-interface.adoc<br>M doc/manuals/chapters/overview.adoc<br>M doc/manuals/osmocbc-usermanual.adoc<br>4 files changed, 62 insertions(+), 22 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc</span><br><span>index 095aed5..5abb3a8 100644</span><br><span>--- a/doc/manuals/chapters/configuration.adoc</span><br><span>+++ b/doc/manuals/chapters/configuration.adoc</span><br><span>@@ -8,6 +8,7 @@</span><br><span> subsequently distributes it among the (matching) cells within the BSC</span><br><span> coverage area.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+[[config-cbsp]]</span><br><span> ==== Configuring the CBSP connections</span><br><span> </span><br><span> According to 3GPP TS 48.049, a BSC typically operates as a TCP server,</span><br><span>@@ -63,6 +64,7 @@</span><br><span> local-port 48049</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+[[config-ecbe]]</span><br><span> === ECBE (REST Interface) Configuration</span><br><span> </span><br><span> ==== Configuring the IP/Port for ECBE to bind to</span><br><span>diff --git a/doc/manuals/chapters/ecbe-rest-interface.adoc b/doc/manuals/chapters/ecbe-rest-interface.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..2c03880</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/ecbe-rest-interface.adoc</span><br><span>@@ -0,0 +1,49 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[ecbe]]</span><br><span style="color: hsl(120, 100%, 40%);">+== ECBE REST interface</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The ECBE (External Cell Broadcast Entity) REST interface is specified in</span><br><span style="color: hsl(120, 100%, 40%);">+the JSON schema files `cbc.schema.json` and `smscb.schema.json`, which</span><br><span style="color: hsl(120, 100%, 40%);">+are part of the OsmoCBC distribution.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The REST interface binds to the IP and TCP port as configured and</span><br><span style="color: hsl(120, 100%, 40%);">+can be reached at `http://IP:PORT/api/ecbe/v1`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE:: It is your responsibility to properly secure access to the REST</span><br><span style="color: hsl(120, 100%, 40%);">+interface endpoint to ensure only legitimate users can access it. This</span><br><span style="color: hsl(120, 100%, 40%);">+may be achieved via packet filtering and a reverse HTTP proxy.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== API endpoints</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== `POST /api/ecbe/v1/message`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command is used to create a new SMSCB or ETWS message inside the CBC.</span><br><span style="color: hsl(120, 100%, 40%);">+The `cbc_messsage` type as specified in the JSON schema (<<ecbe-json>>).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== `DELETE /api/ecbe/v1/message/:message_id`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This command is used to delete an existing SMSCB or ETWS message from the CBC.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The `:message_id` parameter is the decimal integer representation of the</span><br><span style="color: hsl(120, 100%, 40%);">+cbc_message.smscb.message_id that was specified when creating the</span><br><span style="color: hsl(120, 100%, 40%);">+message via the POST command stated above.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[ecbe-json]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== JSON Schema</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== `cbc.schema.json`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This is the main JSOM schema for osmo-cbc. In many places, it</span><br><span style="color: hsl(120, 100%, 40%);">+references `smscb.schema.json` described further below.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/../../cbc.schema.json[]</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== `smscb.schema.json`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This JSON schema describes a lot of the basic data types relevant for</span><br><span style="color: hsl(120, 100%, 40%);">+SMSCB. It is used heavily by `cbc.schema.json` described above.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/../../smscb.schema.json[]</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span>diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc</span><br><span>index 2077878..3063ff7 100644</span><br><span>--- a/doc/manuals/chapters/overview.adoc</span><br><span>+++ b/doc/manuals/chapters/overview.adoc</span><br><span>@@ -49,29 +49,16 @@</span><br><span> the CBC doesn't need to know each and every BSC in the network. It</span><br><span> simply only accepts incoming CBSP connections.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+For more information, see <<config-cbsp>> on how CBSP is configured.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-=== REST interface</span><br><span style="color: hsl(120, 100%, 40%);">+=== ECBE REST interface</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The REST interface is specified in the JSON schema files</span><br><span style="color: hsl(0, 100%, 40%);">-`cbc.schema.json` and `smscb.schema.json`, which are part of the OsmoCBC</span><br><span style="color: hsl(0, 100%, 40%);">-distribution.</span><br><span style="color: hsl(120, 100%, 40%);">+3GPP does not specify the external interface by which competent</span><br><span style="color: hsl(120, 100%, 40%);">+authorities can submit SMSCB and/or ETWS messages to a CBC.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-The REST interface currently binds to TCP port 12345 (on INADRR_ANY) and</span><br><span style="color: hsl(0, 100%, 40%);">-can be reached at http://localhost:1234/api/ecbe/v1"</span><br><span style="color: hsl(120, 100%, 40%);">+Hence, a non-standard, Osmocom specific HTTP/REST/JSON based interface</span><br><span style="color: hsl(120, 100%, 40%);">+is offered for external entities to create and delete SMSCB and ETWS</span><br><span style="color: hsl(120, 100%, 40%);">+messages within the CBC. This interface is called ECBE.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-NOTE:: It is your responsibility to properly secure access to the REST</span><br><span style="color: hsl(0, 100%, 40%);">-interface endpoint to ensure only legitimate users can access it. This</span><br><span style="color: hsl(0, 100%, 40%);">-may be achieved via packet filtering and a reverse HTTP proxy.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== POST /api/ecbe/v1/message</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This command is used to create a new SMSCB or ETWS message inside the CBC.</span><br><span style="color: hsl(0, 100%, 40%);">-The `cbc_messsage` type as specified in the JSON schema.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-==== DELETE /api/ecbe/v1/message/:message_id</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-This command is used to delete an existing SMSCB or ETWS message from the CBC.</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-The `:message_id` parameter is the decimal integer representation of the</span><br><span style="color: hsl(0, 100%, 40%);">-cbc_message.smscb.message_id that was specified when creating the</span><br><span style="color: hsl(0, 100%, 40%);">-message via the POST command stated above.</span><br><span style="color: hsl(120, 100%, 40%);">+For more information, see <<ecbe>> on the ECBE API definition and <<config-ecbe>></span><br><span style="color: hsl(120, 100%, 40%);">+on how it is configured.</span><br><span>diff --git a/doc/manuals/osmocbc-usermanual.adoc b/doc/manuals/osmocbc-usermanual.adoc</span><br><span>index 967ec96..e08586d 100644</span><br><span>--- a/doc/manuals/osmocbc-usermanual.adoc</span><br><span>+++ b/doc/manuals/osmocbc-usermanual.adoc</span><br><span>@@ -16,6 +16,8 @@</span><br><span> </span><br><span> include::{srcdir}/chapters/introspection.adoc[]</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/ecbe-rest-interface.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> include::./common/chapters/counters-overview.adoc[]</span><br><span> </span><br><span> include::{srcdir}/chapters/counters.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-cbc/+/22405">change 22405</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-cbc/+/22405"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-cbc </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I358f72331aa9832cc56c67396eb41b62307a3258 </div>
<div style="display:none"> Gerrit-Change-Number: 22405 </div>
<div style="display:none"> Gerrit-PatchSet: 6 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>