Major Documentation update
* add command line help * add basic user manual * add vty reference manual * install example configuration Change-Id: Idf49d7fcee2b11638945baa25064273a7e5e5e61
This commit is contained in:
parent
2f551c1179
commit
a3c73d9212
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -169,5 +169,8 @@ AC_OUTPUT(
|
|||
src/Makefile
|
||||
contrib/Makefile
|
||||
tests/Makefile
|
||||
doc/Makefile
|
||||
doc/examples/Makefile
|
||||
doc/manuals/Makefile
|
||||
contrib/systemd/Makefile
|
||||
Makefile)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
SUBDIRS = \
|
||||
examples \
|
||||
manuals \
|
||||
$(NULL)
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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@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>
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
:gfdl-enabled:
|
||||
:program-name: OsmoCBC
|
||||
|
||||
OsmoCBC User Manual
|
||||
====================
|
||||
Harald Welte <hwelte@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[]
|
||||
|
|
@ -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>
|
||||
|
||||
|
|
@ -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"
|
||||
|
|
@ -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>
|
||||
|
|
@ -74,7 +74,7 @@ static const struct log_info log_info = {
|
|||
};
|
||||
|
||||
static const char cbc_copyright[] =
|
||||
"Copyright (C) 2019 by Harald Welte <laforge@gnumonks.org>\r\n"
|
||||
"Copyright (C) 2019-2021 by Harald Welte <laforge@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 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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue