This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
laforge gerrit-no-reply at lists.osmocom.orglaforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-cbc/+/22005 )
Change subject: Major Documentation update
......................................................................
Major Documentation update
* add command line help
* add basic user manual
* add vty reference manual
* install example configuration
Change-Id: Idf49d7fcee2b11638945baa25064273a7e5e5e61
---
M .gitignore
M Makefile.am
M configure.ac
M contrib/jenkins.sh
A doc/Makefile.am
A doc/examples/Makefile.am
R doc/examples/osmo-cbc/osmo-cbc.cfg
A doc/manuals/Makefile.am
A doc/manuals/chapters/counters.adoc
A doc/manuals/chapters/overview.adoc
A doc/manuals/chapters/running.adoc
A doc/manuals/osmocbc-usermanual-docinfo.xml
A doc/manuals/osmocbc-usermanual.adoc
A doc/manuals/osmocbc-vty-reference.xml
A doc/manuals/regen_doc.sh
A doc/manuals/vty/cbc_vty_additions.xml
M src/cbc_main.c
17 files changed, 355 insertions(+), 8 deletions(-)
Approvals:
Jenkins Builder: Verified
laforge: Looks good to me, approved
diff --git a/.gitignore b/.gitignore
index e01642c..925f48d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,6 +54,7 @@
doc/manuals/*__*.png
doc/manuals/*.check
doc/manuals/generated/
-doc/manuals/osmomsc-usermanual.xml
+doc/manuals/osmobsc-usermanual.xml
doc/manuals/common
doc/manuals/build
+doc/manuals/vty/cbc_vty_reference.xml
diff --git a/Makefile.am b/Makefile.am
index 6e0fa11..d292296 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,9 +1,9 @@
AUTOMAKE_OPTIONS = foreign dist-bzip2 1.6
AM_CPPFLAGS = $(all_includes) -I$(top_srcdir)/include
-SUBDIRS = src tests contrib
+SUBDIRS = src doc contrib tests
-EXTRA_DIST = .version git-version-gen doc/examples/osmo-cbc.cfg
+EXTRA_DIST = .version git-version-gen
AM_DISTCHECK_CONFIGURE_FLAGS = \
--with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)
diff --git a/configure.ac b/configure.ac
index 566f8c4..342eb84 100644
--- a/configure.ac
+++ b/configure.ac
@@ -169,5 +169,8 @@
src/Makefile
contrib/Makefile
tests/Makefile
+ doc/Makefile
+ doc/examples/Makefile
+ doc/manuals/Makefile
contrib/systemd/Makefile
Makefile)
diff --git a/contrib/jenkins.sh b/contrib/jenkins.sh
index ed73b09..e9b976b 100755
--- a/contrib/jenkins.sh
+++ b/contrib/jenkins.sh
@@ -55,8 +55,8 @@
$MAKE distcheck \
|| cat-testlogs.sh
-#if [ "$WITH_MANUALS" = "1" ] && [ "$PUBLISH" = "1" ]; then
-# make -C "$base/doc/manuals" publish
-#fi
+if [ "$WITH_MANUALS" = "1" ] && [ "$PUBLISH" = "1" ]; then
+ make -C "$base/doc/manuals" publish
+fi
osmo-clean-workspace.sh
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..3cb405e
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,4 @@
+SUBDIRS = \
+ examples \
+ manuals \
+ $(NULL)
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
new file mode 100644
index 0000000..7237c1d
--- /dev/null
+++ b/doc/examples/Makefile.am
@@ -0,0 +1,30 @@
+OSMOCONF_FILES = \
+ osmo-cbc/osmo-cbc.cfg
+
+osmoconfdir = $(sysconfdir)/osmocom
+osmoconf_DATA = $(OSMOCONF_FILES)
+
+EXTRA_DIST = $(OSMOCONF_FILES)
+
+CFG_FILES = find $(srcdir) -name '*.cfg*' | sed -e 's,^$(srcdir),,'
+
+dist-hook:
+ for f in $$($(CFG_FILES)); do \
+ j="$(distdir)/$$f" && \
+ mkdir -p "$$(dirname $$j)" && \
+ $(INSTALL_DATA) $(srcdir)/$$f $$j; \
+ done
+
+install-data-hook:
+ for f in $$($(CFG_FILES)); do \
+ j="$(DESTDIR)$(docdir)/examples/$$f" && \
+ mkdir -p "$$(dirname $$j)" && \
+ $(INSTALL_DATA) $(srcdir)/$$f $$j; \
+ done
+
+uninstall-hook:
+ @$(PRE_UNINSTALL)
+ for f in $$($(CFG_FILES)); do \
+ j="$(DESTDIR)$(docdir)/examples/$$f" && \
+ $(RM) $$j; \
+ done
diff --git a/doc/examples/osmo-cbc.cfg b/doc/examples/osmo-cbc/osmo-cbc.cfg
similarity index 100%
rename from doc/examples/osmo-cbc.cfg
rename to doc/examples/osmo-cbc/osmo-cbc.cfg
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
new file mode 100644
index 0000000..ef90e2b
--- /dev/null
+++ b/doc/manuals/Makefile.am
@@ -0,0 +1,23 @@
+EXTRA_DIST = osmocbc-usermanual.adoc \
+ osmocbc-usermanual-docinfo.xml \
+ osmocbc-vty-reference.xml \
+ regen_doc.sh \
+ chapters \
+ vty
+
+if BUILD_MANUALS
+ ASCIIDOC = osmocbc-usermanual.adoc
+ ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+
+ VTY_REFERENCE = osmocbc-vty-reference.xml
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
+
+ BUILT_REFERENCE_XML = $(builddir)/vty/cbc_vty_reference.xml
+ $(builddir)/vty/cbc_vty_reference.xml: $(top_builddir)/src/osmo-cbc
+ mkdir -p $(builddir)/vty
+ $(top_builddir)/src/osmo-cbc --vty-ref-xml > $@
+
+ OSMO_REPOSITORY = osmo-cbc
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
+endif
diff --git a/doc/manuals/chapters/counters.adoc b/doc/manuals/chapters/counters.adoc
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/manuals/chapters/counters.adoc
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..2077878
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,77 @@
+[[overview]]
+== OsmoCBC Overview
+
+=== The 3GPP Cell Broadcast Centre
+
+Within the 3GPP cellular network, the Cell Broadcast Centre is the central
+instance for managing all Cell Broadcast and Emergency Warning functions.
+
+It acts as a gateway between external applications / users, such as government
+authorities for civil protection, and the various components within the 3GPP
+network to actually deliver those broadcast and/or emergency messages.
+
+[[about]]
+=== About OsmoCBC
+
+OsmoCBC is the Osmocom implementation of a Cellular Broadcast Centre (CBC). It
+implements:
+
+- the BSC-CBC interface using the CBSP protocol
+- a HTTP/JSON/RESTful interface for external applications
+- a telnet-based command line interface for configuration and introspection called VTY
+
+OsmoCBC provides mainly the following functionality:
+
+- establishing communication with the various Radio Access Network elements such as BSCs within the network
+- receiving requests to start or remove CBS and ETWS messages from external applications
+- distributing the CBS and/or ETWS messages
+has connection with the various RANs of the 3GPP cellular network
+
+Future versions of OsmoCBC are expected to contain the RNC-CBC interface
+with the SABP protocol, as well as the MME-CBC interface using the SBcAP
+protocol. Should you be interested in contributing to this effort,
+please contact the author of this document.
+
+=== CBSP implementation
+
+CBSP is a Layer 5 protocol operating on top of TCP/IP, established
+between the CBC and the various BSCs of a cellular network.
+
+According to 3GPP, the CBSP is typically established from the CBC to the
+BSC. This means that the CBSP operates as TCP client and the BSCs
+operate as TCP servers. The disadvantage of this is that it requires
+the CBC to have out-of-band, prior knowledge about all the BSCs in the
+network, as well as their IP addresses.
+
+OsmoCBC also supports a slightly modified mode of operation, where the
+CBC operates as TCP server, and the BSCs as TCP clients. This means
+that all BSCs need to know the IP address of the CBC. In this situation,
+the CBC doesn't need to know each and every BSC in the network. It
+simply only accepts incoming CBSP connections.
+
+
+=== 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.
+
+The REST interface currently binds to TCP port 12345 (on INADRR_ANY) and
+can be reached at http://localhost:1234/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.
+
+==== 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.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..5cbe873
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,21 @@
+== Running OsmoCBC
+
+The OsmoCBC executable (`osmo-cbc`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-cbc* [-h|-V] [-D] [-c 'CONFIGFILE']
+
+=== OPTIONS
+
+*-h, --help*::
+ Print a short help message about the supported options.
+*-V, --version*::
+ Print the compile-time version number of the program.
+*-D, --daemonize*::
+ Fork the process as a daemon into background.
+*-c, --config-file 'CONFIGFILE'*::
+ Specify the file and path name of the configuration file to be
+ used. If none is specified, use `osmo-bsc.cfg` in the current
+ working directory.
diff --git a/doc/manuals/osmocbc-usermanual-docinfo.xml b/doc/manuals/osmocbc-usermanual-docinfo.xml
new file mode 100644
index 0000000..528635c
--- /dev/null
+++ b/doc/manuals/osmocbc-usermanual-docinfo.xml
@@ -0,0 +1,47 @@
+<revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>January 4th, 2021</date>
+ <authorinitials>HW</authorinitials>
+ <revremark>
+ Initial version
+ </revremark>
+ </revision>
+</revhistory>
+
+<authorgroup>
+ <author>
+ <firstname>Harald</firstname>
+ <surname>Welte</surname>
+ <email>hwelte at sysmocom.de</email>
+ <authorinitials>HW</authorinitials>
+ <affiliation>
+ <shortaffil>sysmocom</shortaffil>
+ <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+ <jobtitle>Managing Director</jobtitle>
+ </affiliation>
+ </author>
+</authorgroup>
+
+<copyright>
+ <year>2021</year>
+ <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being just 'Foreword',
+ 'Acknowledgements' and 'Preface', with no Front-Cover Texts,
+ and no Back-Cover Texts. A copy of the license is included in
+ the section entitled "GNU Free Documentation License".
+ </para>
+ <para>
+ The Asciidoc source code of this manual can be found at
+ <ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+ http://git.osmocom.org/osmo-gsm-manuals/
+ </ulink>
+ </para>
+</legalnotice>
diff --git a/doc/manuals/osmocbc-usermanual.adoc b/doc/manuals/osmocbc-usermanual.adoc
new file mode 100644
index 0000000..391a9f1
--- /dev/null
+++ b/doc/manuals/osmocbc-usermanual.adoc
@@ -0,0 +1,29 @@
+:gfdl-enabled:
+:program-name: OsmoCBC
+
+OsmoCBC User Manual
+====================
+Harald Welte <hwelte at sysmocom.de>
+
+
+include::./common/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::{srcdir}/chapters/running.adoc[]
+
+include::./common/chapters/counters-overview.adoc[]
+
+include::{srcdir}/chapters/counters.adoc[]
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]
diff --git a/doc/manuals/osmocbc-vty-reference.xml b/doc/manuals/osmocbc-vty-reference.xml
new file mode 100644
index 0000000..8e05aee
--- /dev/null
+++ b/doc/manuals/osmocbc-vty-reference.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ex:ts=2:sw=42sts=2:et
+ -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
+"http://docbook.org/xml/5.0/dtd/docbook.dtd" [
+<!ENTITY chapter-vty SYSTEM "./common/chapters/vty.xml" >
+<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
+]>
+
+<book>
+ <info>
+ <revhistory>
+ <revision>
+ <revnumber>v1</revnumber>
+ <date>6th January 2021</date>
+ <authorinitials>hw</authorinitials>
+ <revremark>Initial</revremark>
+ </revision>
+ </revhistory>
+
+ <title>OsmoCBC VTY Reference</title>
+
+ <copyright>
+ <year>2021</year>
+ </copyright>
+
+ <legalnotice>
+ <para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
+ </para>
+ </legalnotice>
+ </info>
+
+ <!-- Main chapters-->
+ &chapter-vty;
+</book>
+
diff --git a/doc/manuals/regen_doc.sh b/doc/manuals/regen_doc.sh
new file mode 100755
index 0000000..c2a5d4c
--- /dev/null
+++ b/doc/manuals/regen_doc.sh
@@ -0,0 +1,17 @@
+#!/bin/sh -x
+
+if [ -z "$DOCKER_PLAYGROUND" ]; then
+ echo "You need to set DOCKER_PLAYGROUND"
+ exit 1
+fi
+
+SCRIPT=$(realpath "$0")
+MANUAL_DIR=$(dirname "$SCRIPT")
+
+COMMIT=${COMMIT:-$(git log -1 --format=format:%H)}
+
+cd "$DOCKER_PLAYGROUND/scripts" || exit 1
+
+OSMO_CBC_BRANCH=$COMMIT ./regen_doc.sh osmo-cbc 4264 \
+ "$MANUAL_DIR/chapters/counters_generated.adoc" \
+ "$MANUAL_DIR/vty/cbc_vty_reference.xml"
diff --git a/doc/manuals/vty/cbc_vty_additions.xml b/doc/manuals/vty/cbc_vty_additions.xml
new file mode 100644
index 0000000..b27bb7d
--- /dev/null
+++ b/doc/manuals/vty/cbc_vty_additions.xml
@@ -0,0 +1,18 @@
+<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
+ <node id='config-cbc'>
+ <description>This node allows to configure the CBC. Will enter the CBC specific VTY configuration node.</description>
+ <command id='peer NAME'>
+ <description>
+ Configure a CBC RAN peer (BSC, ...). Will enter a sub-node where parameters about that peer can be configured. The NAME has local significance only (for VTY and logging).
+ </description>
+ </command>
+ <command id='unknown-peers (accept|reject)'>
+ <description>
+ Whether or not the CBC should accept incoming CBSP/TCP connections from unknown peers, i.e. such peers that don't have an explicit 'peer' configuration.
+ </description>
+ </command>
+ </node>
+ <node id='config-cbc-peer'>
+ <description>This node allows to configure one CBC RAN peer (BSC, ...)</description>
+ </node>
+</vtydoc>
diff --git a/src/cbc_main.c b/src/cbc_main.c
index 77020db..06969e7 100644
--- a/src/cbc_main.c
+++ b/src/cbc_main.c
@@ -74,7 +74,7 @@
};
static const char cbc_copyright[] =
- "Copyright (C) 2019 by Harald Welte <laforge at gnumonks.org>\r\n"
+ "Copyright (C) 2019-2021 by Harald Welte <laforge at gnumonks.org>\r\n"
"License AGPLv3+: GNU Affero GPL Version 3 or later <http://gnu.org/licenses/agpl-3.0.html>\r\n"
"This is free software: you are free ot change and redistribute it.\r\n"
"There is NO WARRANTY, to the extent permitted by law.\r\n\r\n"
@@ -98,18 +98,54 @@
static void print_help(void)
{
- /* FIXME */
+ printf("Supported options:\n");
+ printf(" -h --help This text.\n");
+ printf(" -D --daemonize Fork the process into a background daemon.\n");
+ printf(" -c --config-file filename The config file to use.\n");
+ printf(" -V --version Print the version of OsmoMSC.\n");
+
+ printf("\nVTY reference generation:\n");
+ printf(" --vty-ref-mode MODE VTY reference generation mode (e.g. 'expert').\n");
+ printf(" --vty-ref-xml Generate the VTY reference XML output and exit.\n");
+}
+
+static void handle_long_options(const char *prog_name, const int long_option)
+{
+ static int vty_ref_mode = VTY_REF_GEN_MODE_DEFAULT;
+
+ switch (long_option) {
+ case 1:
+ vty_ref_mode = get_string_value(vty_ref_gen_mode_names, optarg);
+ if (vty_ref_mode < 0) {
+ fprintf(stderr, "%s: Unknown VTY reference generation "
+ "mode '%s'\n", prog_name, optarg);
+ exit(2);
+ }
+ break;
+ case 2:
+ fprintf(stderr, "Generating the VTY reference in mode '%s' (%s)\n",
+ get_value_string(vty_ref_gen_mode_names, vty_ref_mode),
+ get_value_string(vty_ref_gen_mode_desc, vty_ref_mode));
+ vty_dump_xml_ref_mode(stdout, (enum vty_ref_gen_mode) vty_ref_mode);
+ exit(0);
+ default:
+ fprintf(stderr, "%s: error parsing cmdline options\n", prog_name);
+ exit(2);
+ }
}
static void handle_options(int argc, char **argv)
{
while (1) {
int option_index = 0, c;
+ static int long_option = 0;
static const struct option long_options[] = {
{ "help", 0, 0, 'h' },
{ "daemonize", 0, 0, 'D' },
{ "config-file", 1, 0, 'c' },
{ "version", 0, 0, 'V' },
+ { "vty-ref-mode", 1, &long_option, 1},
+ { "vty-ref-xml", 0, &long_option, 2},
{ NULL, 0, 0, 0 }
};
@@ -122,6 +158,9 @@
print_help();
exit(0);
break;
+ case 0:
+ handle_long_options(argv[0], long_option);
+ break;
case 'D':
cmdline_config.daemonize = true;
break;
--
To view, visit https://gerrit.osmocom.org/c/osmo-cbc/+/22005
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings
Gerrit-Project: osmo-cbc
Gerrit-Branch: master
Gerrit-Change-Id: Idf49d7fcee2b11638945baa25064273a7e5e5e61
Gerrit-Change-Number: 22005
Gerrit-PatchSet: 4
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/20210106/95e145ae/attachment.htm>