diff --git a/.gitignore b/.gitignore index e01642c..925f48d 100644 --- a/.gitignore +++ b/.gitignore @@ -54,6 +54,7 @@ doc/manuals/*.pdf 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 @@ AC_OUTPUT( 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 @@ DISTCHECK_CONFIGURE_FLAGS="--enable-external-tests $CONFIG" \ $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 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 @@ + + + 1 + January 4th, 2021 + HW + + Initial version + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + + + 2021 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + 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 + + +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 @@ + + + + +]> + + + + + + v1 + 6th January 2021 + hw + Initial + + + + OsmoCBC VTY Reference + + + 2021 + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + + 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 @@ + + + This node allows to configure the CBC. Will enter the CBC specific VTY configuration node. + + + 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). + + + + + 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. + + + + + This node allows to configure one CBC RAN peer (BSC, ...) + + 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 struct log_info log_info = { }; static const char cbc_copyright[] = - "Copyright (C) 2019 by Harald Welte \r\n" + "Copyright (C) 2019-2021 by Harald Welte \r\n" "License AGPLv3+: GNU Affero GPL Version 3 or later \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 struct { 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 @@ static void handle_options(int argc, char **argv) print_help(); exit(0); break; + case 0: + handle_long_options(argv[0], long_option); + break; case 'D': cmdline_config.daemonize = true; break;