diff --git a/.gitignore b/.gitignore index f662e2a6..49b2cfb7 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,8 @@ include/osmocom/hnbap/hnbap_ies_defs.h include/osmocom/rua/rua_ies_defs.h include/osmocom/ranap/ranap_ies_defs.h include/osmocom/sabp/sabp_ies_defs.h + +doc/manuals/build +doc/manuals/common +doc/manuals/generated +doc/manuals/*.pdf diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am index 91aa8f85..7a76e907 100644 --- a/doc/manuals/Makefile.am +++ b/doc/manuals/Makefile.am @@ -1,9 +1,16 @@ EXTRA_DIST = \ + osmohnbgw-usermanual.adoc \ + osmohnbgw-usermanual-docinfo.xml \ + chapters \ osmohnbgw-vty-reference.xml \ regen_doc.sh \ vty if BUILD_MANUALS + ASCIIDOC = osmohnbgw-usermanual.adoc + ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc + include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc + VTY_REFERENCE = osmohnbgw-vty-reference.xml include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 00000000..2368b4ff --- /dev/null +++ b/doc/manuals/chapters/overview.adoc @@ -0,0 +1,56 @@ +[[overview]] +== Overview + + +[[intro_overview]] +=== About OsmoHNBGW + +OsmoHNBGW implements the Home NodeB Gateway function in the 3G network architecture. It serves +as a gateway between the classic 3G core network (CN) domain with its IuCS and IuPS interface +and the femtocell based RAN. + +A typical 3G network consisting of Osmocom components will look as illustrated in the following +diagram: + +[[fig-3g]] +.Typical 3G network architecture used with OsmoHNBGW +---- + +------------+ +--------+ +----------+ +---------+ + UE <-->| hNodeB |<--Iuh---->| HNB-GW |<--IuCS-->| OsmoMSC |<--GSUP-->| OsmoHLR | + UE <-->| femto cell | ...-->| | ...-->| | | | + | | | | +----------+ +---------| + +------------+<--GTP-U | | + \ | | +------+ +------+ + | | |<--IuPS-->| SGSN |<--GTP-C-->| GGSN | + | +--------+ ...-->| | GTP-U-->| | + | +------+ / +------+ + \_______________________________/ +---- + +The HNB-GW performs a translation interface between the IuCS/IuPS interfaces on the one hand +side, and the Iuh interface on the or ther hand: + +---- + Iuh IuCS/IuPS + +NAS +----+----+ +----+----+ +Non-Access Stratum | CC | MM | | CC | MM | +- - - - - - - - - - - +----+----+-------+ +----+----+ + | RANAP | | H | RANAP | +Access Stratum +---------+ HNBAP | N +---------+ - - SCCP USER SAP + | RUA | | B | SUA | \ + +---------+-------+ - +---------+ | + | SCTP | G | SCTP | } SIGTRAN + +-----------------+ W +---------+ | + | IP | | IP | / + +-----------------+ +---------+ +---- + +On the femtocell (Home NodeB) side, OsmoHNBGW implements the Iuh interface as specified by 3GPP. + +=== The Iuh interface + +Iuh consists of the following sub-layers: + +- HNBAP (Home NodeB Application Part) +- RUA (RANAP User Adaptation, between RANAP and SCTP diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc new file mode 100644 index 00000000..41909e25 --- /dev/null +++ b/doc/manuals/chapters/running.adoc @@ -0,0 +1,37 @@ +== Running OsmoHNBGW + +The OsmoHNBGW executable (`osmo-hnbgw`) offers the following command-line +arguments: + +=== SYNOPSIS + +*osmo-hnbgw* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] + +=== OPTIONS + +*-h, --help*:: + Print a short help message about the supported options +*-V, --version*:: + Print the compile-time version number of the OsmoHNBGW program +*-d, --debug 'DBGMASK','DBGLEVELS'*:: + Set the log subsystems and levels for logging to stderr. This + has mostly been superseded by VTY-based logging configuration, + see <> for further information. +*-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-msc.cfg` in the current + working directory. +*-s, --disable-color*:: + Disable colors for logging to stderr. This has mostly been + deprecated by VTY based logging configuration, see <> + for more information. +*-T, --timestamp*:: + Enable time-stamping of log messages to stderr. This has mostly + been deprecated by VTY based logging configuration, see + <> for more information. +*-e, --log-level 'LOGLEVEL'*:: + Set the global log level for logging to stderr. This has mostly + been deprecated by VTY based logging configuration, see + <> for more information. diff --git a/doc/manuals/osmohnbgw-usermanual-docinfo.xml b/doc/manuals/osmohnbgw-usermanual-docinfo.xml new file mode 100644 index 00000000..404d2a1e --- /dev/null +++ b/doc/manuals/osmohnbgw-usermanual-docinfo.xml @@ -0,0 +1,51 @@ + + + 1 + November 30th, 2019 + HW + + Initial version + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + + + 2019 + 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-hnbgw/ + + and of the common chapters at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + diff --git a/doc/manuals/osmohnbgw-usermanual.adoc b/doc/manuals/osmohnbgw-usermanual.adoc new file mode 100644 index 00000000..3f3c9c3b --- /dev/null +++ b/doc/manuals/osmohnbgw-usermanual.adoc @@ -0,0 +1,35 @@ +:gfdl-enabled: +:program-name: OsmoHNBGW + +OsmoHNBGW User Manual +===================== +Harald Welte + + +include::./common/chapters/preface.adoc[] + +include::{srcdir}/chapters/overview.adoc[] + +include::{srcdir}/chapters/running.adoc[] + +// include::{srcdir}/chapters/control.adoc[] + +// include::./common/chapters/counters-overview.adoc[] + +// include::{srcdir}/chapters/counters.adoc[] + +include::./common/chapters/vty.adoc[] + +include::./common/chapters/logging.adoc[] + +// include::{srcdir}/chapters/net.adoc[] + +// include::./common/chapters/control_if.adoc[] + +include::./common/chapters/port_numbers.adoc[] + +include::./common/chapters/bibliography.adoc[] + +include::./common/chapters/glossary.adoc[] + +include::./common/chapters/gfdl.adoc[]