diff options
47 files changed, 1820 insertions, 429 deletions
diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..4da10e7 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,13 @@ +; This file is for unifying the coding style for different editors and IDEs. +; See http://editorconfig.org for details. + +# Top-most EditorConfig file. +root = true + +[build/*.inc] +indent_size = 8 +indent_style = tab +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + diff --git a/build/Makefile.asciidoc.inc b/build/Makefile.asciidoc.inc index 1b7375e..e2e8ad2 100644 --- a/build/Makefile.asciidoc.inc +++ b/build/Makefile.asciidoc.inc @@ -20,11 +20,7 @@ BUILDDIR = $(OSMO_GSM_MANUALS_DIR)/build COMMONDIR = $(OSMO_GSM_MANUALS_DIR)/common GIT_VERSION := $(shell git describe --abbrev=4 --dirty --always --tags) -GIT_DATE := $(shell $(OSMO_GSM_MANUALS_DIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at" ../.`) - -# prepend the document name with the version numbe suffix -#DOCS_VER = $(foreach P, $(ASCIIDOC_NAME), $(P)-v$(shell xmllint --recover --xpath "//revnumber[position()=last()]/text()" $(P)-docinfo.xml 2>/dev/null)) -#PDFS = $(DOCS_VER:%=%.pdf) +GIT_DATE := $(shell $(OSMO_GSM_MANUALS_DIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at"`) # generate list of PDFs that we're supposed to render ASCIIDOC_NAME = $(patsubst %.adoc,%,$(ASCIIDOC)) @@ -38,8 +34,20 @@ CLEAN_FILES += $(ASCIIDOC_PDF) $(ASCIIDOC_NAME:%=%.html) UPLOAD_FILES += $(ASCIIDOC_PDF) ABS_SRCDIR := $(or $(abs_srcdir),$(shell realpath $(srcdir))) -ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -a srcdir='$(ABS_SRCDIR)' -a commondir='$(COMMONDIR)' -DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes -P draft.watermark=0 +ASCIIDOC_OPTS := \ + -f $(BUILDDIR)/mscgen-filter.conf \ + -f $(BUILDDIR)/diag-filter.conf \ + -f $(BUILDDIR)/docinfo-releaseinfo.conf \ + -f $(BUILDDIR)/graphviz-filter.conf \ + -a srcdir='$(ABS_SRCDIR)' \ + -a commondir='$(COMMONDIR)' \ + $(NULL) +DBLATEX_OPTS := \ + --config $(OSMO_GSM_MANUALS_DIR)/build/dblatex_config.xml \ + -s $(ASCIIDOCSTYLE) \ + -P draft.mode=yes \ + -P draft.watermark=0 \ + $(NULL) ifeq (,$(BUILD_RELEASE)) REVNUMBER := DRAFT $(GIT_VERSION) @@ -52,6 +60,12 @@ A2X_OPTS := -L --asciidoc-opts="$(ASCIIDOC_OPTS)" --dblatex-opts="$(DBLATEX_OPTS all: $(ASCIIDOC_PDF) +# ln: a2x can't use a different output file. To support out-of-tree builds, +# we create a symlink at $(builddir)/srcfile.adoc pointing at +# $(srcdir)/srcfile.adoc. $< is the $(srcdir)/srcfile.adoc, +# $(notdir) is like basename from coreutils, and $(builddir) is $PWD. +# TEXINPUTS: find LaTeX includes like \includegraphics{./common/images/sysmocom.pdf} +# in $(OSMO_GSM_MANUALS_DIR). $(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \ $(ASCIIDOC_DEPS) \ $(ASCIIDOCSTYLE) \ @@ -59,20 +73,10 @@ $(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \ $(COMMONDIR)/images/* \ build common - # a2x can't use a different output file. To support out-of-tree builds, - # we create a symlink at $(builddir)/srcfile.adoc pointing at - # $(srcdir)/srcfile.adoc. $< is the $(srcdir)/srcfile.adoc, - # $(notdir) is like basename from coreutils, and $(builddir) is $PWD. if ! [ -f $(notdir $<) ]; then \ ln -s $< $(notdir $<); \ fi - # TEXINPUTS: find LaTeX includes like \includegraphics{./common/images/sysmocom.pdf} - # in $(OSMO_GSM_MANUALS_DIR). - @test -n "$(BUILD_RELEASE)" && echo -e "\n\n\ - NOTE: TO REMOVE DRAFT MODE, YOU NEED TO EDIT build/custom-dblatex.sty\n\ - and remove three lines starting with '% \"DRAFT\" on first page'\n" \ - || true TEXINPUTS="$(OSMO_GSM_MANUALS_DIR)" \ a2x -vv $(A2X_OPTS) $(notdir $<) @@ -81,23 +85,22 @@ check: $(MAKE) $(ASCIIDOC_CHECKS); \ fi +# ln: out-of-tree building: use a symlink to the output file like done in +# the non-check build above, so the relative include paths work the same. +# touch: Make absolutely sure that the %.check target is updated. +# grep: Do print the WARNING output but return error if any was found +# (grep -v would omit the WARNING output from the log). $(ASCIIDOC_CHECKS): %.check: %.adoc %-docinfo.xml \ $(ASCIIDOCSTYLE) \ $(COMMONDIR)/chapters/*.adoc \ $(ASCIIDOC_DEPS) \ build common - # out-of-tree building: use a symlink to the output file like done in - # the non-check build above, so the relative include paths work the - # same. if ! [ -f $(notdir $<) ]; then \ ln -s $< $(notdir $<); \ fi asciidoc -v $(ASCIIDOC_OPTS) $(notdir $<) > $(notdir $@) 2>&1 - # Make absolutely sure that the %.check target is updated. touch $(notdir $@) - # Do print the WARNING output but return error if any was found - # (grep -v would omit the WARNING output from the log). @grep WARNING $(notdir $@) && exit 1 || exit 0 diff --git a/build/Makefile.common.inc b/build/Makefile.common.inc index 0fda918..80f2c19 100644 --- a/build/Makefile.common.inc +++ b/build/Makefile.common.inc @@ -9,9 +9,11 @@ SSH_COMMAND = ssh -o 'UserKnownHostsFile=$(OSMO_GSM_MANUALS_DIR)/build/known_hosts' -p 48 UPLOAD_PATH ?= generic@sysmocom-downloads:documents SYMLINKS = common build -CLEAN_FILES += $(SYMLINKS) +CLEAN_FILES += $(SYMLINKS) $(SHRINK_MARKER) PDF_FILES = $(patsubst %.adoc,%.pdf,$(ASCIIDOC)) $(patsubst %.xml,%.pdf,$(VTY_REFERENCE)) -OSMO_REPOSITORY ?= osmo-gsm-manuals +SHRINK_MARKER = generated/.pdf_shrink_marker +PUBLISH_REF ?= master +PUBLISH_TEMPDIR = _publish_tmpdir # Prefix (Makefile.am sets this to configure's --prefix when including) prefix ?= /usr/local @@ -19,16 +21,28 @@ prefix ?= /usr/local $(SYMLINKS): ln -s $(OSMO_GSM_MANUALS_DIR)/$@ $@ -upload: $(UPLOAD_FILES) - rsync -avz $(UPLOAD_FILES) $(UPLOAD_PATH)/ - -clean: - -rm -rf $(CLEAN_FILES) +# Reduce pdf size by storing the embedded images with less quality (SYS#6380) +shrink: $(SHRINK_MARKER) +$(SHRINK_MARKER): $(UPLOAD_FILES) + $(OSMO_GSM_MANUALS_DIR)/build/shrink-pdfs.sh $(UPLOAD_FILES) -distclean: clean +# Publish to $UPLOAD_PATH +upload: shrink + rsync -avz $(UPLOAD_FILES) $(UPLOAD_PATH)/ -publish: $(UPLOAD_FILES) - rsync -avz -e "$(SSH_COMMAND)" $(UPLOAD_FILES) docs@ftp.osmocom.org:web-files/latest/ +# Publish to https://ftp.osmocom.org/docs/ +publish: shrink + [ -n "$(OSMO_REPOSITORY)" ] || exit 1 + rm -rf "$(PUBLISH_TEMPDIR)" + mkdir -p "$(PUBLISH_TEMPDIR)/$(OSMO_REPOSITORY)/$(PUBLISH_REF)" + cp $(UPLOAD_FILES) "$(PUBLISH_TEMPDIR)/$(OSMO_REPOSITORY)/$(PUBLISH_REF)" + cd "$(PUBLISH_TEMPDIR)" && \ + rsync \ + -avzR \ + -e "$(SSH_COMMAND)" \ + "$(OSMO_REPOSITORY)" \ + docs@ftp.osmocom.org:web-files/ + rm -rf "$(PUBLISH_TEMPDIR)" # Install and uninstall targets # Notes about OSMO_GSM_MANUALS_NO_INSTALL: @@ -37,6 +51,7 @@ publish: $(UPLOAD_FILES) # - installing manuals by default is fine, because Osmocom projects won't include # the whole Makefile.common.inc unless --enable-manuals is passed to configure. install: $(PDF_FILES) + [ -n "$(OSMO_REPOSITORY)" ] || exit 1 if [ "$(OSMO_GSM_MANUALS_NO_INSTALL)" != "1" ]; then \ for i in $(PDF_FILES); do \ install -vDm644 "$$i" "$(DESTDIR)$(prefix)/share/doc/$(OSMO_REPOSITORY)-doc/$$i" || exit 1; \ @@ -44,8 +59,14 @@ install: $(PDF_FILES) fi uninstall: + [ -n "$(OSMO_REPOSITORY)" ] || exit 1 if [ "$(OSMO_GSM_MANUALS_NO_INSTALL)" != "1" ]; then \ for i in $(PDF_FILES); do \ rm -v "$(DESTDIR)$(prefix)/share/doc/$(OSMO_REPOSITORY)-doc/$$i"; \ done; \ fi + +clean: + -rm -rf $(CLEAN_FILES) + +distclean: clean diff --git a/build/Makefile.docbook.inc b/build/Makefile.docbook.inc index eb0ee25..6eb48d0 100644 --- a/build/Makefile.docbook.inc +++ b/build/Makefile.docbook.inc @@ -28,15 +28,33 @@ UPLOAD_FILES += $(DOCBOOKS_PDF) all: $(DOCBOOKS_PDF) # Allow the users to re-define the include directory -INC_DIR ?= $(PWD)/generated +INC_DIR ?= $(shell pwd)/generated # Lint the file %.xml-lint: %.xml xmllint --xinclude --postvalid --noout $< +GIT_VERSION := $(shell git describe --abbrev=4 --dirty --always --tags) +GIT_DATE := $(shell $(OSMO_GSM_MANUALS_DIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at" ../.`) +ifeq (,$(BUILD_RELEASE)) + REVNUMBER := DRAFT $(GIT_VERSION) +else + REVNUMBER := $(GIT_VERSION) +endif + # Create a PDF file and lint it before # xslt path: find includes in both $(OSMO_GSM_MANUALS_DIR)/common/chapters and $(builddir)/generated %.pdf: %.xml %.xml-lint $(DOCBOOKS_DEPS) build common - dblatex --xslt-opts="--path $(realpath $(OSMO_GSM_MANUALS_DIR))/common/chapters:$(INC_DIR)" \ - $(dblatex_quiet) -P draft.mode=no -o $@ $< - + set -x && \ + export GIT_DATE="$(GIT_DATE)" && \ + export REVNUMBER="$(REVNUMBER)" && \ + export TEMPFILE="$(INC_DIR)/_temp_$(notdir $<)" && \ + $(OSMO_GSM_MANUALS_DIR)/build/docbook-set-revhistory.py "$<" && \ + dblatex \ + --config $(OSMO_GSM_MANUALS_DIR)/build/dblatex_config.xml \ + --xslt-opts="--path $(realpath $(OSMO_GSM_MANUALS_DIR))/common/chapters:$(INC_DIR)" \ + $(dblatex_quiet) \ + -P draft.mode=no \ + -o $@ \ + "$$TEMPFILE" && \ + rm $$TEMPFILE diff --git a/build/dblatex_config.xml b/build/dblatex_config.xml new file mode 100644 index 0000000..bd89ea7 --- /dev/null +++ b/build/dblatex_config.xml @@ -0,0 +1,16 @@ +<?xml version="1.0" ?> +<!-- + ==================================================================== + Replace inkscape by rsvg-convert to convert SVG graphics + https://sourceforge.net/p/dblatex/mailman/message/37005820/ + ==================================================================== +--> +<config xmlns="http://dblatex.sourceforge.net/config"> + <imagedata> + <converter src="svg" dst="*" docformat="pdf"> + <command> + rsvg-convert -a -f %(dst)s -o %(output)s %(input)s + </command> + </converter> + </imagedata> +</config> diff --git a/build/diag-filter.conf b/build/diag-filter.conf index 0c30db7..cc6b941 100644 --- a/build/diag-filter.conf +++ b/build/diag-filter.conf @@ -3,7 +3,7 @@ # [seqdiag-filter-style] -seqdiag-style=template="seqdiag-block",subs=(),posattrs=("style","target"),filter='seqdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} - && echo " "' +seqdiag-style=template="seqdiag-block",subs=(),posattrs=("style","target"),filter='seqdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} - && echo " "' [blockdef-listing] template::[seqdiag-filter-style] @@ -16,12 +16,12 @@ template::[filter-diag-pngsvg-blockmacro] [filter-diag-pngsvg-blockmacro] {target%}{counter2:target-number} -{target%}{set2:target:{docname}__{target-number}.{format={basebackend-docbook!png}{basebackend-docbook?png}}} +{target%}{set2:target:{docname}__{target-number}.{format={basebackend-docbook!svg}{basebackend-docbook?svg}}} | template::[image-blockmacro] [blockdiag-filter-style] -blockdiag-style=template="blockdiag-block",subs=(),posattrs=("style","target"),filter='blockdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} - && echo " "' +blockdiag-style=template="blockdiag-block",subs=(),posattrs=("style","target"),filter='blockdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} - && echo " "' [blockdef-listing] template::[blockdiag-filter-style] @@ -35,7 +35,7 @@ template::[filter-diag-pngsvg-blockmacro] [actdiag-filter-style] -actdiag-style=template="actdiag-block",subs=(),posattrs=("style","target"),filter='actdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} - && echo " "' +actdiag-style=template="actdiag-block",subs=(),posattrs=("style","target"),filter='actdiag -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} - && echo " "' [blockdef-listing] template::[actdiag-filter-style] @@ -49,7 +49,7 @@ template::[filter-diag-pngsvg-blockmacro] [nwdiag-filter-style] -nwdiag-style=template="nwdiag-block",subs=(),posattrs=("style","target"),filter='nwdiag3 -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} - && echo " "' +nwdiag-style=template="nwdiag-block",subs=(),posattrs=("style","target"),filter='nwdiag3 -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} - && echo " "' [blockdef-listing] template::[nwdiag-filter-style] @@ -62,7 +62,7 @@ template::[filter-diag-pngsvg-blockmacro] [packetdiag-filter-style] -packetdiag-style=template="packetdiag-block",subs=(),posattrs=("style","target"),filter='packetdiag3 -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} - && echo " "' +packetdiag-style=template="packetdiag-block",subs=(),posattrs=("style","target"),filter='packetdiag3 -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} - && echo " "' [blockdef-listing] template::[packetdiag-filter-style] diff --git a/build/docbook-set-revhistory.py b/build/docbook-set-revhistory.py new file mode 100755 index 0000000..8494ff0 --- /dev/null +++ b/build/docbook-set-revhistory.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +# Rewrite the revhistory part of the document for vty reference (OS#4063) +import os +import shutil +import sys + +xml_in = sys.argv[1] +xml_out = os.environ["TEMPFILE"] +git_date = os.environ["GIT_DATE"] +revnumber = os.environ["REVNUMBER"] + + +def get_author_initials(line): + return line.split("<authorinitials>")[1].split("</authorinitials>")[0] + + +def write_revhistory_block(h_out, author_initials): + h_out.write("<revhistory>\n") + h_out.write("<revision>\n") + h_out.write(f"<revnumber>{revnumber}</revnumber>\n") + h_out.write(f"<date>{git_date}</date>\n") + h_out.write(f"<authorinitials>{author_initials}</authorinitials>\n") + h_out.write("<revremark>Automatically Generated VTY Reference</revremark>\n") + h_out.write("</revision>\n") + h_out.write("</revhistory>\n") + + +def set_revhistory(): + """ + Replace the part of the docbook that looks like the following, and copy + all other lines. Just using python's xml library would be better, but it + fails on docbook's custom DTDs. + <revhistory> + <revision> + <revnumber>v1</revnumber> + <date>18th September 2017</date> + <authorinitials>nh</authorinitials> + <revremark>Initial</revremark> + </revision> + </revhistory> + """ + before = 0 + inside = 1 + after = 2 + + pos = before + author_initials = "" + + with open(xml_out, "w") as h_out: + with open(xml_in, "r") as h_in: + for line in h_in.readlines(): + if pos == before: + if "<revhistory>" in line: + h_out.write(line.split("<revhistory>")[0] + "\n") + pos = inside + + if pos in [before, after]: + h_out.write(line) + + if pos == inside: + if "<authorinitials>" in line: + author_initials = get_author_initials(line) + if "</revhistory>" in line: + write_revhistory_block(h_out, author_initials) + h_out.write(line.split("</revhistory>")[1]) + pos = after + + +def main(): + if xml_in.endswith("-vty-reference.xml"): + print(f"Changing revhistory to {revnumber}, {git_date}...") + set_revhistory() + else: + print("Copying without change of revhistory...") + shutil.copyfile(xml_in, xml_out) + + +main() diff --git a/build/graphviz-filter.conf b/build/graphviz-filter.conf new file mode 100644 index 0000000..bf32927 --- /dev/null +++ b/build/graphviz-filter.conf @@ -0,0 +1,24 @@ +# +# AsciiDoc Graphviz filter configuration file. +# + +[graphviz-filter-style] +graphviz-style=template="graphviz{format?-{format}}-block",subs=(),posattrs=("style","target","layout","format"),filter='dot -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T {format=svg} && echo " "' + +[blockdef-open] +template::[graphviz-filter-style] + +[blockdef-listing] +template::[graphviz-filter-style] + +[paradef-default] +template::[graphviz-filter-style] + +[graphviz-block] +template::[filter-image-svgblockmacro] + +[filter-image-svgblockmacro] +{target%}{counter2:target-number} +{target%}{set2:target:{docname}__{target-number}.svg} +| +template::[image-blockmacro] diff --git a/build/mscgen-filter.conf b/build/mscgen-filter.conf index fa8f03e..0e6cfa0 100644 --- a/build/mscgen-filter.conf +++ b/build/mscgen-filter.conf @@ -4,7 +4,7 @@ # [mscgen-filter-style] -mscgen-style=template="mscgen-block",subs=(),posattrs=("style","target"),filter='./build/filter-wrapper.py mscgen -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!png}{basebackend-docbook?png}} -' +mscgen-style=template="mscgen-block",subs=(),posattrs=("style","target"),filter='./build/filter-wrapper.py mscgen -o "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" -T{format={basebackend-docbook!svg}{basebackend-docbook?svg}} -' [blockdef-listing] template::[mscgen-filter-style] @@ -17,7 +17,7 @@ template::[filter-image-pngsvg-blockmacro] [filter-image-pngsvg-blockmacro] {target%}{counter2:target-number} -{target%}{set2:target:{docname}__{target-number}.{format={basebackend-docbook!png}{basebackend-docbook?png}}} +{target%}{set2:target:{docname}__{target-number}.{format={basebackend-docbook!svg}{basebackend-docbook?svg}}} | template::[image-blockmacro] diff --git a/build/shrink-pdfs.sh b/build/shrink-pdfs.sh new file mode 100755 index 0000000..a919ac3 --- /dev/null +++ b/build/shrink-pdfs.sh @@ -0,0 +1,27 @@ +#!/bin/sh -e +# Reduce pdf size by storing the embedded images with less quality (SYS#6380) +# usage: shrink-pdfs.sh first.pdf [second.pdf [...]] +mkdir -p generated + +for i in $@; do + out="generated/shrink_temp.pdf" + ps2pdf -dPDFSETTINGS=/ebook "$i" "$out" + + size_old=$(du "$i" | cut -f1) + size_old_h=$(du -h "$i" | cut -f1) + size_new=$(du "$out" | cut -f1) + size_new_h=$(du -h "$out" | cut -f1) + + if [ "$size_new" -lt "$size_old" ]; then + echo "* $i: $size_new_h (shrunk from $size_old_h)" + mv "$out" "$i" + else + echo "* $i: $size_old_h" + rm "$out" + fi +done + +# Add a marker so the Makefile knows that the shrink script ran. The generated +# dir is already in the gitignore files of repositories using osmo-gsm-manuals, +# so put it there. +touch generated/.pdf_shrink_marker diff --git a/check-depends.sh b/check-depends.sh index f072fd8..46da717 100755 --- a/check-depends.sh +++ b/check-depends.sh @@ -15,6 +15,6 @@ check_dep_bin asciidoc asciidoc check_dep_bin dblatex dblatex check_dep_bin packetdiag3 python3-nwdiag check_dep_bin dot graphviz -check_dep_bin inkscape inkscape +check_dep_bin rsvg-convert librsvg2-bin echo "All dependencies installed!" diff --git a/common/chapters/bibliography.adoc b/common/chapters/bibliography.adoc index 06b1fb4..9d635b0 100644 --- a/common/chapters/bibliography.adoc +++ b/common/chapters/bibliography.adoc @@ -141,6 +141,10 @@ (GPRS); Base Station System (BSS) - Serving GPRS Support Node (SGSN); BSS GPRS protocol (BSSGP) https://www.3gpp.org/DynaReport/48018.htm +- [[[3gpp-ts-48-049]]] 3GPP TS 48.049: Digital cellular communications system; + Base Station Controller - Cell Broadcast Centre (BSC-CBC) interface specification; + Cell Broadcast Service Protocol (CBSP) + https://www.3gpp.org/DynaReport/48049.htm - [[[3gpp-ts-48-056]]] 3GPP TS 48.056: Base Station Controller - Base Transceiver Station (BSC - BTS) interface; Layer 2 specification https://www.3gpp.org/DynaReport/48056.htm diff --git a/common/chapters/cell-broadcast.adoc b/common/chapters/cell-broadcast.adoc index a87efae..c1d9581 100644 --- a/common/chapters/cell-broadcast.adoc +++ b/common/chapters/cell-broadcast.adoc @@ -3,7 +3,7 @@ Normally, all user plane data in GSM/GPRS networks are sent in point-to-point channels from the network to the user. Those are called -"dedicated" radio channels which exist between the network and one +_dedicated_ radio channels which exist between the network and one given phone/subscriber at a time. Cell Broadcast is an exception to that rule. It permits user data @@ -18,7 +18,7 @@ specification is <<3gpp-ts-23-041>>. === Use Cases Cell Broadcast was used for various different use cases primarily in -the 1990ies and early 2000s, including +the 1990s and early 2000s, including * advertisement of the GPS position of the cell tower you're currently camping on * advertisement of the calling codes of your current "home zone", i.e. a @@ -35,39 +35,33 @@ warning systems, such as === Osmocom Cell Broadcast support -* OsmoBTS implements the "SMS BROADCAST COMMAND" Message in RSL - according to Section 8.5.8 of 3GPP TS 08.58 -* OsmoNITB and OsmoBSC implement a VTY command - `bts <0-255> smscb-command <1-4> HEXSTRING` to send a given hex-formatted cell - broadcast message to a specified BTS +* OsmoBTS implements the `SMS BROADCAST COMMAND` Message in A-bis RSL + according to Section 8.5.8 of 3GPP TS 48.058 +* low-level testing/debugging features +** OsmoNITB and OsmoBSC implement a VTY command + `bts <0-255> smscb-command <1-4> HEXSTRING` to send a given hex-formatted cell + broadcast message to a specified BTS. This can be used for low-level debugging +* proper 3GPP-specified CBS/PWS elements and protocols +** OsmoBSC supports routing and distribution of CBS and warning messages +** OsmoBSC implements the BSC-CBC interface using the CBSP protocol +** OsmoCBC implements the central function of a _Cell Broadcast Centre_, + receiving cell broadcast and warning messages from external entities + via a REST based HTTP interface, and distributing it throughout the + cellular network. +** OsmoCBC implements the BSC-CBC interface using the CBSP protocol (for + 2G/GSM RAN) +** OsmoCBC implements the MME-CBC interface using the SBcAP protocol (for + 4G/LTE RAN) + [mscgen] ---- include::osmocom-cbs.msc[] ---- -==== What's missing - -What's missing (for production operation in larger networks) - -* mechanism to broadcast one (set of) cell broadcast messages from the - BSC to multiple/all BTSs, rather than one BTS individually -* OsmoBTS reporting of current CBCH load -* BSC scheduler scheduling multiple alternating sets of CBCH messages - based on the current CBCH load reported by BTS -* external interface from BSC to a Cell Broadcast Center (CBC), e.g. - according to 3GPP TS 48.049 -* an Osmocom implementation of the Cell Broadcast Center (OsmoCBC) - which can manage and distribute messages to multiple BSCs and which - has an external interface by which cell-broadcast can be entered - into the network - -If you would like to contribute in any of those areas (by means of -code or funding), please reach out to us any time. - === Message Structure -* Each message has a meximum of 15 pages +* Each message has a maximum of 15 pages * Each page is 82 bytes of data, resulting in 93 characters in GSM 7-bit default alphabet * Messages are broadcast on logical channels (more like an address) diff --git a/common/chapters/counters-overview.adoc b/common/chapters/counters-overview.adoc index 8f9a29a..b51036f 100644 --- a/common/chapters/counters-overview.adoc +++ b/common/chapters/counters-overview.adoc @@ -124,5 +124,83 @@ OsmoBSC(config-stats)# enable <4> IP address of the statsd server. <5> UDP port of the statsd server. Statsd by default listens to port 8125. -Setting up a statsd server and configuring the visualization is beyond the -scope of this document. +You can use Netdata (https://learn.netdata.cloud/) as a statsd server which does not require special configuration +to show rate counters. +By default all the rate counters will be exposed to the StatsD plugin (listening on 127.0.0.1:8125) and displayed on the +Netdata dashboard available via: http://localhost:19999 +The list of available charts which includes all the rate counters reported via statsD is available through: +http://localhost:19999/api/v1/charts + +=== Socket stats + +libosmocore provides features to monitor the status of TCP connections. This +can be a helpful source of information when the links between network +components are unreliable (e.g. satellite link between BTS and BSC). + +NOTE: This feature is only available for certain types of TCP connections. At +the moment only RSL/OML connections between OsmoBSC and the connected BTSs can +be monitored. + +==== Configuration + +The gathering of the TCP connection statistics is done via syscalls. This has +to be taken into account for the configuration. Since syscalls are rather +expensive and time consuming the overall performance of the application may +suffer when many TCP connections are present. This may be the case for BSCs +with a large number of BTSs connected to it. + +The statistics are gathered in batches per interval. A batch size of 5 would +mean that only 5 TCP connections per interval are evaluated and the next 5 +connections in the next interval and so on. + +It is recommended to choose a large reporting interval and a reasonable small +batch size to distribute the syscall load as even as possible. + +.Report statistics to statsd +==== +---- +OsmoBSC> enable +OsmoBSC# configure terminal +stats-tcp interval 10 <1> +stats-tcp batch-size 5 <2> +---- +==== + +<1> Set the gathering interval (sec.) +<2> Set how many TCP sockets statistics to gather per interval. + +==== Generated stats items + +[options="header"] +|=== +| Name | Description +| tcp:unacked | unacknowledged packets. +| tcp:lost | unacknowledged packets. +| tcp:retrans | lost packets. +| tcp:rtt | retransmitted packets. +| tcp:rcv_rtt | roundtrip-time (receive). +| tcp:notsent_bytes | bytes not yet sent. +| tcp:rwnd_limited | time (usec) limited by receive window. +| tcp:sndbuf_limited | Time (usec) limited by send buffer. +| tcp:reord_seen | reordering events seen. +|=== + +The item group index is the file descriptor number. The item group name +consists of a static prefix (e.g. "ipa-rsl"), followed by the IP addresses +and ports of both peers. + +.VTY output of a stats item group of a TCP connection +==== +---- +stats tcp (15)('ipa-rsl,r=10.9.1.143:38455<->l=10.9.1.162:3003'): + unacknowledged packets: 0 + lost packets: 0 + retransmitted packets: 0 + roundtrip-time: 583 + roundtrip-time (receive): 0 + bytes not yet sent: 0 + time (usec) limited by receive window: 0 + Time (usec) limited by send buffer: 0 + reordering events seen: 0 +---- +==== diff --git a/common/chapters/cs7-config.adoc b/common/chapters/cs7-config.adoc index 62e85bb..09b526c 100644 --- a/common/chapters/cs7-config.adoc +++ b/common/chapters/cs7-config.adoc @@ -50,6 +50,7 @@ cs7 instance 0 point-code 0.23.1 asp asp-clnt-OsmoMSC-A-Iu 2905 0 m3ua remote-ip 127.0.0.1 + role asp sctp-role client as as-clnt-OsmoMSC-A-Iu m3ua asp asp-clnt-OsmoMSC-A-Iu @@ -76,9 +77,6 @@ for SCCP-level message exchange between all the connected programs. === Connect to STP Instance -By default, an STP instance is assumed to listen on the default M3UA port -(2905) on the local host (127.0.0.1). - Establishing an SCCP/M3UA link towards a remote STP instance can be configured as: @@ -89,10 +87,25 @@ cs7 instance 0 remote-ip 10.23.24.1 # optional: local bind to a specific IP local-ip 10.9.8.7 + role asp + sctp-role client ---- Be aware that such an `asp` needs to be linked to an `as`, see <<as_and_asp>>. +By default, an STP instance is assumed to listen on the default M3UA port +(2905) on the local host. That means in general `127.0.0.1` will be used as +default remote SCTP address, and `::1` will be added to the SCTP association if +IPv6 support is available on the system. + +NOTE: OsmoSTP listens by default on `::` if IPv6 is enabled on the system, +and on `0.0.0.0` otherwise. Address `::` actually superseeds `0.0.0.0`, meaning +it will listen on all IPv4 and IPv6 addresses available on the system. + +CAUTION: Some applications overwrite the default target remote address to +be `localhost`. If IPv6 support is available on the system, `localhost` will +usually resolve to `::1`, otherwise it will usually resolve to `127.0.0.1`. + === Local Point-Code Each CNI program on an SCCP/M3UA link typically has a local point-code, @@ -225,6 +238,7 @@ cs7 instance 0 asp my-asp 2905 0 m3ua # where to reach the STP: remote-ip 127.0.0.1 + role asp sctp-role client as my-as m3ua asp my-asp @@ -241,6 +255,8 @@ are not linked: cs7 instance 0 asp my-asp 2905 0 m3ua remote-ip 127.0.0.1 + role asp + sctp-role client as my-as m3ua routing-key 2 0.23.1 ---- @@ -251,6 +267,8 @@ To *fix* above config, link the `asp` to an `as` by adding `asp my-asp`: cs7 instance 0 asp my-asp 2905 0 m3ua remote-ip 127.0.0.1 + role asp + sctp-role client as my-as m3ua asp my-asp routing-key 2 0.23.1 diff --git a/common/chapters/gb-ns2-configuration-timer.adoc b/common/chapters/gb-ns2-configuration-timer.adoc deleted file mode 100644 index ab8585f..0000000 --- a/common/chapters/gb-ns2-configuration-timer.adoc +++ /dev/null @@ -1,36 +0,0 @@ -==== Gb/NS Timer configuration - -The NS protocol features a number of configurable timers. - -.List of configurable NS timers -|=== -|tns-block|(un)blocking timer timeout (secs) -|tns-block-retries|(un)blocking timer; number of retries -|tns-reset|reset timer timeout (secs) -|tns-reset-retries|reset timer; number of retries -|tns-test|test timer timeout (secs) -|tns-alive|alive timer timeout (secs) -|tns-alive-retries|alive timer; number of retries -|tsns-prov|SNS provision timeout (secs) used by all SNS auto configuration procedures. -|tsns-size-retries|SNS Size procedure; number of retries -|tsns-config-retries|SNS Config procedure; number of retries -|=== - -All timer can be configured by vty configuration - -.Example of timeouts ----- -ns - timer tns-block 3 - timer tns-block-retries 3 - timer tns-reset 3 - timer tns-reset-retries 3 - timer tns-test 30 - timer tns-alive 3 - timer tns-alive-retries 10 - timer tsns-prov 10 - timer tsns-size-retries 3 - timer tsns-config-retries 3 ----- - -// FIXME: ladder diagrams for every timer diff --git a/common/chapters/gb-ns2-configuration.adoc b/common/chapters/gb-ns2-configuration.adoc deleted file mode 100644 index b8f2b03..0000000 --- a/common/chapters/gb-ns2-configuration.adoc +++ /dev/null @@ -1,172 +0,0 @@ -=== Gb/NS configuration - -This section describes the configuration that libosmogb exposes via the -VTY and is valid for OsmoSGSN and OsmoGbProxy. - -==== Gb over Frame Relay over E1/T1 - -The Gb over Frame Relay over E1/T1 requires: - -* a hdlc interface -* a frame relay role (fr or frnet) -* the DLCI - -.Example: Gb over Frame Relay configuration #1 ----- -ns - bind fr sitea1 <1> - fr hdlc1 frnet <2> - nse 2001 <3> - nsvci fr sitea1 dlci 16 nsvci 11 ----- -<1> a Gb-over-FR bind with the name sitea1 -<2> connect the hdlc1 device with the role frnet to sitea1 -<3> one NSE (2001) with a single NS-VCI 11 on sitea1 with DLCI 16 - -.Example: Gb over Frame Relay configuration #2 ----- -ns - bind fr sitea1 <1> - fr hdlc1 frnet <2> - bind fr sitea2 - fr hdlc2 frnet - bind fr sitea3 - fr hdlc3 frnet - bind fr sitea4 - fr hdlc4 frnet - bind fr siteb1 - fr hdlc5 frnet - bind fr siteb2 - fr hdlc6 frnet - bind fr sitec1 - fr hdlc7 frnet - bind fr sitec2 - fr hdlc8 frnet - nse 2001 <3> - nsvci fr sitea1 dlci 16 nsvci 11 - nsvci fr sitea2 dlci 17 nsvci 12 - nsvci fr sitea3 dlci 18 nsvci 13 - nsvci fr sitea4 dlci 19 nsvci 14 - nse 2002 <4> - nsvci fr siteb5 dlci 20 nsvci 15 - nsvci fr siteb6 dlci 21 nsvci 16 - nse 2003 <5> - nsvc fr sitec7 dlci 22 nsvci 17 - nsvc fr sitec8 dlci 23 nsvci 18 ----- -<1> a Gb-over-FR bind with the name sitea1 -<2> connect the hdlc1 device with the role frnet to sitea1 -<3> one NSE (2001) with four NS-VCI (11..14) on sitea1..4 with their respective DLCI -<4> another NSE (2002) with two NS-VCI (15..16) on siteb1..2 with their respective DLCI -<5> another NSE (2003) with two NS-VCI (17..18) on sitec1..2 with their respective DLCI - - -==== Gb over IP "ip.access style" - -The Gb over IP "ip.access style" can be used with a dynamic configuration or with a -static configuration - -The static configuration requires to configure all endpoints on the BSS and SGSN. -In constrast the dynamic configuration allows the SGSN to have only a reduced configuration. - -===== Gb over IP "ip.access style" dynamic configuration - -.Example: Gb over IP/UDP ip.access style dynamic configuration (SGSN) ----- -ns - bind udp ran1 <1> - listen 10.100.1.1 23000 <2> - accept-ipaccess <3> ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.1.1:23000 -<3> accept unknown BSS of ip.access style - -.Example: Gb over IP/UDP "ip.access style" dynamic configuration (GbProxy as BSS) ----- -ns - bind udp ran1 <1> - listen 10.100.0.1 23000 <2> - nse 1001 <3> - nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.1.1:23000 -<3> accept unknown BSS of ip.access style - -NOTE: The OsmoPCU supports ip.access style Gb/NS but doesn't support this vty configuration because -it's receiving the configuration from the BTS/BSC. - -===== Gb over IP "ip.access style" static configuration - -.Example: Gb over IP/UDP "ip.access style" dynamic configuration (SGSN) ----- -ns - bind udp ran1 <1> - listen 10.100.0.1 23000 <2> ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.0.1:23000 - -.Example: Gb over IP/UDP "ip.access style" dynamic configuration (GbProxy as BSS) ----- -ns - bind udp ran1 <1> - listen 10.100.0.1 23000 <2> - nse 1001 <3> - nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.0.1:23000 -<3> NSE 1001 with nsvc 1001 as ip.access style - -NOTE: The OsmoPCU supports "ip.access style" Gb/NS but doesn't support this vty configuration because -it's receiving the configuration from the BTS/BSC. - - -==== Gb over IP 3GPP static configuration - -A static IP/UDP configuration without SNS as specified by 3GPP 48.016. - -.Example: Gb over IP/UDP static configuration BSS/SGSN ----- -ns - bind udp ran1 <1> - listen 10.100.0.1 23000 <2> - nse 1001 <3> - nsvc udp ran1 10.100.1.1 23000 signalling-weight 2 data-weight 2 - nsvc udp ran1 10.100.1.2 23000 <4> ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.0.1:23000 -<3> add NSE 1001 with 2 NSVC -<4> short configuration with default signalling and data weight of 1 - -==== Gb over IP 3GPP auto configuration as BSS - -IP/UDP auto-configuration with initial endpoints to an SGSN. -The auto-configuration will use the first bind to connect to the -first endpoint. If this fails Osmocom will iterate over all endpoints and binds to find -a working combination. - -.Example: Gb over IP/UDP auto-configuration as BSS ----- -ns - bind udp ran1 <1> - listen 10.100.0.1 23000 <2> - bind udp ran2 - listen 10.100.0.2 23000 - bind udp ran3 - listen 10.100.0.3 23000 - nse 1001 <3> - ip-sns-bind ran1 <4> - ip-sns-bind ran2 - ip-sns-endpoint 10.100.1.1 <5> - ip-sns-endpoint 10.100.1.2 ----- -<1> create a IP/UDP bind with name ran1 -<2> bind to 10.100.0.1:23000 -<3> add NSE 1001 with 2 initial SNS endpoints -<4> add ran1 to the list of available endpoints -<5> add 10.100.1.1 as initial endpoint - diff --git a/common/chapters/gb-ns2-nsvc-states-alive.dot b/common/chapters/gb-ns2-nsvc-states-alive.dot new file mode 100644 index 0000000..7e919c1 --- /dev/null +++ b/common/chapters/gb-ns2-nsvc-states-alive.dot @@ -0,0 +1,6 @@ + +digraph G { + DISABLED -> ALIVE; + ALIVE -> RECOVERING [label="test procedure timeout"]; + RECOVERING -> ALIVE [label="test procedure success"]; +} diff --git a/common/chapters/gb-ns2-nsvc-states-reset-block.dot b/common/chapters/gb-ns2-nsvc-states-reset-block.dot new file mode 100644 index 0000000..b1825d5 --- /dev/null +++ b/common/chapters/gb-ns2-nsvc-states-reset-block.dot @@ -0,0 +1,9 @@ +digraph G { + DISABLED -> RESET [label="transport layer available"]; + RESET -> BLOCKED [label="reset ack"]; + BLOCKED -> UNBLOCKED [label="unblock"]; + UNBLOCKED -> BLOCKED [label="block"]; + BLOCKED -> RESET [label="test procedure timeout"]; + UNBLOCKED -> RESET [label="test procedure timeout"]; +} + diff --git a/common/chapters/gb-ns2.adoc b/common/chapters/gb-ns2.adoc index 38f7c4f..e72fa50 100644 --- a/common/chapters/gb-ns2.adoc +++ b/common/chapters/gb-ns2.adoc @@ -58,7 +58,7 @@ shall use for each NS-VC, and which DLCIs to use on them. The Linux kernel Frame Relay LMI support (which only implements the user role anyway) is not used. Instead, the ITU-T Q.933 LMI is implemented -as part of the Osmocom NS code in libosmogb. Osmocom NS code configres +as part of the Osmocom NS code in libosmogb. Osmocom NS code configures the `hdlcX` device to match the correct mode (fr) and lmi (none). This is equivalent to the user-space command `sethdlc hdlcX fr lmi none`. The net-devices will be also brought _up_ by the Osmocom NS code equivalent to @@ -180,7 +180,319 @@ A NS-VC is always bound to a NSE and the bind (NS-VL). The NSVC can be either persistent or dynamic. -=== VTY +=== Gb/NS configuration -This section describes the VTY commands to inspect or interact with the NS. +This section describes the configuration that libosmogb exposes via the +VTY and is valid for OsmoSGSN and OsmoGbProxy. +==== Gb over Frame Relay over E1/T1 + +The Gb over Frame Relay over E1/T1 requires: + +* a hdlc interface +* a frame relay role (fr or frnet) +* the DLCI + +.Example: Gb over Frame Relay configuration #1 +---- +ns + bind fr sitea1 <1> + fr hdlc1 frnet <2> + nse 2001 <3> + nsvci fr sitea1 dlci 16 nsvci 11 +---- +<1> a Gb-over-FR bind with the name sitea1 +<2> connect the hdlc1 device with the role frnet to sitea1 +<3> one NSE (2001) with a single NS-VCI 11 on sitea1 with DLCI 16 + +.Example: Gb over Frame Relay configuration #2 +---- +ns + bind fr sitea1 <1> + fr hdlc1 frnet <2> + bind fr sitea2 + fr hdlc2 frnet + bind fr sitea3 + fr hdlc3 frnet + bind fr sitea4 + fr hdlc4 frnet + bind fr siteb1 + fr hdlc5 frnet + bind fr siteb2 + fr hdlc6 frnet + bind fr sitec1 + fr hdlc7 frnet + bind fr sitec2 + fr hdlc8 frnet + nse 2001 <3> + nsvci fr sitea1 dlci 16 nsvci 11 + nsvci fr sitea2 dlci 17 nsvci 12 + nsvci fr sitea3 dlci 18 nsvci 13 + nsvci fr sitea4 dlci 19 nsvci 14 + nse 2002 <4> + nsvci fr siteb5 dlci 20 nsvci 15 + nsvci fr siteb6 dlci 21 nsvci 16 + nse 2003 <5> + nsvc fr sitec7 dlci 22 nsvci 17 + nsvc fr sitec8 dlci 23 nsvci 18 +---- +<1> a Gb-over-FR bind with the name sitea1 +<2> connect the hdlc1 device with the role frnet to sitea1 +<3> one NSE (2001) with four NS-VCI (11..14) on sitea1..4 with their respective DLCI +<4> another NSE (2002) with two NS-VCI (15..16) on siteb1..2 with their respective DLCI +<5> another NSE (2003) with two NS-VCI (17..18) on sitec1..2 with their respective DLCI + + +==== Gb over IP "ip.access style" + +The Gb over IP "ip.access style" can be used with a dynamic configuration or with a +static configuration + +The static configuration requires to configure all endpoints on the BSS and SGSN. +In contrast the dynamic configuration allows the SGSN to have only a reduced configuration. + +===== Gb over IP "ip.access style" dynamic configuration + +.Example: Gb over IP/UDP ip.access style dynamic configuration (SGSN) +---- +ns + bind udp ran1 <1> + listen 10.100.1.1 23000 <2> + accept-ipaccess <3> +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.1.1:23000 +<3> accept unknown BSS of ip.access style + +.Example: Gb over IP/UDP "ip.access style" dynamic configuration (GbProxy as BSS) +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.1.1:23000 +<3> accept unknown BSS of ip.access style + +NOTE: The OsmoPCU supports ip.access style Gb/NS but doesn't support this vty configuration because +it's receiving the configuration from the BTS/BSC. + +===== Gb over IP "ip.access style" static configuration + +.Example: Gb over IP/UDP "ip.access style" static configuration (BSS & SGSN) +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> NSE 1001 with nsvc 1001 as ip.access style + +NOTE: The OsmoPCU supports "ip.access style" Gb/NS but doesn't support this vty configuration because +it's receiving the configuration from the BTS/BSC. + + +==== Gb over IP 3GPP static configuration + +A static IP/UDP configuration without SNS as specified by 3GPP 48.016. + +.Example: Gb over IP/UDP static configuration BSS/SGSN +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc udp ran1 10.100.1.1 23000 signalling-weight 2 data-weight 2 + nsvc udp ran1 10.100.1.2 23000 <4> +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> add NSE 1001 with 2 NSVC +<4> short configuration with default signalling and data weight of 1 + +==== Gb over IP 3GPP auto configuration as BSS + +IP/UDP auto-configuration with initial endpoints to an SGSN. +The auto-configuration will use the first bind to connect to the +first endpoint. If this fails Osmocom will iterate over all endpoints and binds to find +a working combination. + +.Example: Gb over IP/UDP auto-configuration as BSS +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + bind udp ran2 + listen 10.100.0.2 23000 + bind udp ran3 + listen 10.100.0.3 23000 + nse 1001 <3> + ip-sns-bind ran1 <4> + ip-sns-bind ran2 + ip-sns-remote 10.100.1.1 23000 <5> + ip-sns-remote 10.100.1.2 23000 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> add NSE 1001 with 2 initial SNS endpoints +<4> add ran1 to the list of available endpoints +<5> add 10.100.1.1 as initial endpoint + + +==== Gb/NS Timer configuration + +The NS protocol features a number of configurable timers. + +.List of configurable NS timers +|=== +|tns-block|(un)blocking timer timeout (secs) +|tns-block-retries|(un)blocking timer; number of retries +|tns-reset|reset timer timeout (secs) +|tns-reset-retries|reset timer; number of retries +|tns-test|test timer timeout (secs) +|tns-alive|alive timer timeout (secs) +|tns-alive-retries|alive timer; number of retries +|tsns-prov|SNS provision timeout (secs) used by all SNS auto configuration procedures. +|tsns-size-retries|SNS Size procedure; number of retries +|tsns-config-retries|SNS Config procedure; number of retries +|=== + +All timer can be configured by vty configuration + +.Example of timeouts +---- +ns + timer tns-block 3 + timer tns-block-retries 3 + timer tns-reset 3 + timer tns-reset-retries 3 + timer tns-test 30 + timer tns-alive 3 + timer tns-alive-retries 10 + timer tsns-prov 10 + timer tsns-size-retries 3 + timer tsns-config-retries 3 +---- + +// FIXME: ladder diagrams for every timer + +=== Gb/NS maintenance + +This section describes common maintenance procedures. + +[[ns2-nse-states]] +==== NSE states + +A NSE can have the following states: + +.NSE states +* ALIVE +* DEAD + +For FR, IPA: The NSE is ALIVE if there is at least one NSVC in state UNBLOCKED. +For IP-SNS/UDP: The NSE is ALIVE if there is at least one NSVC ALIVE and the sum of all ALIVE NSVCs signalling weights > 0 and data weights > 0. + +The state of the NSE is shown by vty. + +.show ns +---- +GbProxy# show ns nsei 1234 +NSEI 01234: UDP, DEAD <1> + FSM Instance Name: 'GPRS-NS2-SNS-BSS(NSE01234-SNS)[0x6120000012a0]', ID: 'NSE01234-SNS' + Log-Level: 'DEBUG', State: 'BSS_SIZE' + Timer: 1 + Maximum number of remote NS-VCs: 8192, IPv4 Endpoints: 8192, IPv6 Endpoints: 8192 + 1 NS-VC: + NSVCI none: DISABLED DYNAMIC data_weight=1 sig_weight=1 udp)[127.0.0.1]:23000<>[127.0.0.1]:22000 +---- +<1> NSE state + +==== NSVC states + +A NSVC can have the following states: + +.nsvc states +[options="header"] +|========================================================= +| State | transport UNITDATA | Description + +| DISABLED | No | Either the transport layer is unavailable (FR) or this NSVC is currently used by IP-SNS dynamic configuration. +| RESET | No | Sending out RESET PDU and awaiting data. +| BLOCKED | No* | The NSVC has been BLOCKED. * see 3GPP TS 48.016 § 7.2 exception +| UNBLOCKED/ALIVE | Yes | The NSVC transport UNITDATA. +| RECOVERING | No | The NSVC test procedure timed out. NSVC type is a IP-SNS which don't use RESET/BLOCK/UNBLOCK. + +|========================================================= + +[[fig-nsvc-states-reset-block]] +.Simplified state diagram for RESET BLOCK UNBLOCK NSVCs +[graphviz] +---- +include::gb-ns2-nsvc-states-reset-block.dot[] +---- + +[[fig-nsvc-states-alive]] +.Simplified state diagram for IP-SNS/UDP +[graphviz] +---- +include::gb-ns2-nsvc-states-alive.dot[] +---- + +==== Show information of a specific NSE + +The NSE 1234 has been configured for as BSS with IP-SNS configuration. + +.show ns on a dynamic configured IP-SNS NSE +---- +GbProxy# show ns nsei 1234 +NSEI 01234: UDP, DEAD <1> + FSM Instance Name: 'GPRS-NS2-SNS-BSS(NSE01234-SNS)[0x6120000012a0]', ID: 'NSE01234-SNS' + Log-Level: 'DEBUG', State: 'BSS_SIZE' <2> + Timer: 1 + Maximum number of remote NS-VCs: 8192, IPv4 Endpoints: 8192, IPv6 Endpoints: 8192 + 1 NS-VC: + NSVCI none: DISABLED DYNAMIC data_weight=1 sig_weight=1 udp)[127.0.0.1]:23000<>[127.0.0.1]:22000 +---- +<1> A UDP NSE. A NSE can be ALIVE or DEAD +<2> The SNS state. CONFIGURED and LOCAL_PROCEDURE are ALIVE states + +For description of NSE states see <<ns2-nse-states>>. + +.show ns on a frame relay NSE +---- +OsmoNSdummy# show ns nsei 02001 +NSEI 02001: FR, ALIVE <1> + 4 NS-VC: + NSVCI 00001: DISABLED PERSIST data_weight=1 sig_weight=1 fr)netif: hdlcnet1 dlci: 16 <2> + NSVCI 00002: DISABLED PERSIST data_weight=1 sig_weight=1 fr)netif: hdlcnet2 dlci: 17 <3> + NSVCI 00003: DISABLED PERSIST <4> data_weight=1 sig_weight=1 fr)netif: hdlcnet3 dlci: 18 + NSVCI 00004: DISABLED PERSIST data_weight=1 sig_weight=1 fr)netif: hdlcnet4 dlci: 19 +---- +<1> A FR NSE. A NSE can be ALIVE or DEAD +<2> An unblocked NS-VC will be used for data and signalling. data and signalling weight are only relevant for UDP NSVC. +<3> NSVC is still blocked. +<4> A PERSIST NSVC is a configured via VTY. + +==== Blocking a NSVC + +.how to block a single NSVC +---- +OsmoNSdummy# show ns nsei 01234 +NSEI 01234: UDP, ALIVE since 0d 0h 41m 6s + 2 NS-VC: + NSVCI 01234: UNBLOCKED PERSIST udp)[127.0.0.1]:23000\<1234>[127.0.0.1]:22000 ALIVE since 0d 0h 2m 36s + NSVCI 01235: UNBLOCKED PERSIST udp)[127.0.0.1]:23001\<1235>[127.0.0.1]:22001 ALIVE since 0d 0h 41m 6s + +OsmoNSdummy# nsvc 1234 block +The NS-VC 01234 will be blocked. +OsmoNSdummy# show ns nsei 01234 +NSEI 01234: UDP, ALIVE since 0d 0h 42m 7s + 2 NS-VC: + NSVCI 01234: BLOCKED PERSIST udp)[127.0.0.1]:23000\<1234>[127.0.0.1]:22000 DEAD since 0d 0h 3m 37s + NSVCI 01235: UNBLOCKED PERSIST udp)[127.0.0.1]:23001\<1235>[127.0.0.1]:22001 ALIVE since 0d 0h 42m 7s +---- diff --git a/common/chapters/gfdl.adoc b/common/chapters/gfdl.adoc index 00ed4ba..6aa706d 100644 --- a/common/chapters/gfdl.adoc +++ b/common/chapters/gfdl.adoc @@ -246,7 +246,7 @@ l. Preserve all the <<invariant-sections>> of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. m. Delete any section Entitled ``Endorsements''. Such a section - may not be included in the <<modified-vesion>>. + may not be included in the <<modified-version>>. n. Do not retitle any existing section to be Entitled ``Endorsements'' or to conflict in title with any <<invariant-sections>>. o. Preserve any Warranty Disclaimers. diff --git a/common/chapters/glossary.adoc b/common/chapters/glossary.adoc index 926ebd3..bbddcc5 100644 --- a/common/chapters/glossary.adoc +++ b/common/chapters/glossary.adoc @@ -53,8 +53,14 @@ BSSGP:: Base Station Subsystem Gateway Protocol (_3GPP TS 48.018_ <<3gpp-ts-48-018>>) BVCI:: BSSGP Virtual Circuit Identifier +CBC:: + Cell Broadcast Centre; central entity of Cell Broadcast service CBCH:: Cell Broadcast Channel; used to transmit Cell Broadcast SMS (SMS-CB) +CBS:: + Cell Broadcast Service +CBSP:: + Cell Broadcast Service Protocol (_3GPP TS 48.049_ <<3gpp-ts-48-049>>) CC:: Call Control; Part of the GSM Layer 3 Protocol CCCH:: @@ -130,7 +136,7 @@ GSMTAP:: GSM tap; pseudo standard for encapsulating GSM protocol layers over UDP/IP for analysis GSUP:: - Generic ubscriber Update Protocol. Osmocom-specific alternative to TCAP/MAP + Generic Subscriber Update Protocol. Osmocom-specific alternative to TCAP/MAP GT:: Global Title; an address in SCCP GTP:: diff --git a/common/chapters/gsup.adoc b/common/chapters/gsup.adoc index 6d07e6b..f5cce14 100644 --- a/common/chapters/gsup.adoc +++ b/common/chapters/gsup.adoc @@ -349,6 +349,7 @@ Besides a numeric range, the 'presence' column may have 'M' (Mandatory), 'O' (Optional) or 'C' (Conditional). The 'format' column holds either 'V' (Value) or 'TLV' (Tag Length Value). +[[gsup-msg-auth-info-req]] ==== Send Authentication Info Request Direction: SGSN / VLR => HLR @@ -361,12 +362,18 @@ Direction: SGSN / VLR => HLR |28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 |26|AUTS|<<gsup-ie-auts>>|C|TLV|18 |20|RAND|<<gsup-ie-rand>>|C|TLV|18 +|05|PDP info|<<gsup-ie-pdpinfo>>|C|TLV|2-N |=== The conditional 'AUTS' and 'RAND' IEs are both present in case the SIM (via UE) requests an UMTS AKA re-synchronization procedure. Either both optional IEs are present, or none of them. +The conditional 'PDP Info' IE is only present in the CEAI interface used by the +ePDG. It should contain the 'PDP Context ID', 'PDP Address' (dynamic addressing) +and 'Access Point Name' IEs. + +[[gsup-msg-auth-info-err]] ==== Send Authentication Info Error Direction: HLR => SGSN / VLR @@ -379,6 +386,7 @@ Direction: HLR => SGSN / VLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-auth-info-res]] ==== Send Authentication Info Response Direction: HLR => SGSN / VLR @@ -391,6 +399,7 @@ Direction: HLR => SGSN / VLR |03|Auth Tuple|<<gsup-ie-authtuple>>|0-5|TLV|36 |=== +[[gsup-msg-auth-fail-rep]] ==== Authentication Failure Report Direction: SGSN / VLR => HLR @@ -403,6 +412,7 @@ Direction: SGSN / VLR => HLR |28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 |=== +[[gsup-msg-upd-loc-req]] ==== Update Location Request Direction: SGSN / VLR => HLR @@ -415,6 +425,7 @@ Direction: SGSN / VLR => HLR |28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 |=== +[[gsup-msg-upd-loc-err]] ==== Update Location Error Direction: HLR => SGSN / VLR @@ -427,6 +438,7 @@ Direction: HLR => SGSN / VLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-upd-loc-res]] ==== Update Location Result Direction: HLR => SGSN / VLR @@ -439,11 +451,12 @@ Direction: HLR => SGSN / VLR |08|MSISDN|<<gsup-ie-msisdn>>|O|TLV|0-9 |09|HLR Number|<<gsup-ie-hlr>>|O|TLV|0-9 |04|PDP info complete|<<gsup-ie-empty>>|O|TLV|2 -|05|PDP info|<<gsup-ie-pdpinfo>>|O|TLV|1-10 +|05|PDP info|<<gsup-ie-pdpinfo>>|O|TLV|2-N |=== If the PDP info complete IE is present, the old PDP info list shall be cleared. +[[gsup-msg-loc-cancel-req]] ==== Location Cancellation Request Direction: HLR => SGSN / VLR @@ -457,6 +470,14 @@ Direction: HLR => SGSN / VLR |06|Cancellation type|<<gsup-ie-canctype>>|O|TLV|3 |=== +[[gsup-msg-loc-cancel-err]] +==== Location Cancellation Error + +Direction: SGSN / VLR => HLR + +TODO + +[[gsup-msg-loc-cancel-res]] ==== Location Cancellation Result Direction: SGSN / VLR => HLR @@ -469,6 +490,7 @@ Direction: SGSN / VLR => HLR |28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 |=== +[[gsup-msg-purge-ms-req]] ==== Purge MS Request Direction: SGSN / VLR => HLR @@ -482,6 +504,7 @@ Direction: SGSN / VLR => HLR |09|HLR Number|<<gsup-ie-hlr>>|M|TLV|0-9 |=== +[[gsup-msg-purge-ms-err]] ==== Purge MS Error Direction: HLR => SGSN / VLR @@ -494,6 +517,7 @@ Direction: HLR => SGSN / VLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-purge-ms-res]] ==== Purge MS Result Direction: HLR => SGSN / VLR @@ -506,6 +530,7 @@ Direction: HLR => SGSN / VLR |07|Freeze P-TMSI|<<gsup-ie-empty>>|M|TLV|2 |=== +[[gsup-msg-ins-sub-req]] ==== Insert Subscriber Data Request Direction: HLR => SGSN / VLR @@ -525,6 +550,7 @@ Direction: HLR => SGSN / VLR If the PDP info complete IE is present, the old PDP info list shall be cleared. +[[gsup-msg-ins-sub-err]] ==== Insert Subscriber Data Error Direction: SGSN / VLR => HLR @@ -537,6 +563,7 @@ Direction: SGSN / VLR => HLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-ins-sub-res]] ==== Insert Subscriber Data Result Direction: SGSN / VLR => HLR @@ -548,6 +575,7 @@ Direction: SGSN / VLR => HLR |01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10 |=== +[[gsup-msg-del-sub-req]] ==== Delete Subscriber Data Request Direction: HLR => SGSN / VLR @@ -561,6 +589,7 @@ Direction: HLR => SGSN / VLR |10|PDP Context ID|<<gsup-ie-pdpctxid>>|C|TLV|3 |=== +[[gsup-msg-del-sub-err]] ==== Delete Subscriber Data Error Direction: SGSN / VLR => HLR @@ -573,6 +602,7 @@ Direction: SGSN / VLR => HLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-del-sub-res]] ==== Delete Subscriber Data Result Direction: HLR => SGSN / VLR @@ -584,6 +614,7 @@ Direction: HLR => SGSN / VLR |01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10 |=== +[[gsup-msg-proc-supl-serv-req]] ==== Process Supplementary Service Request Direction: bidirectional @@ -602,6 +633,7 @@ This message is used in both directions in case of USSD, because it is not known is it request or response without parsing the GSM 04.80 payload. +[[gsup-msg-proc-supl-serv-err]] ==== Process Supplementary Service Error Direction: EUSE / HLR => MSC @@ -616,6 +648,7 @@ Direction: EUSE / HLR => MSC |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-proc-supl-serv-res]] ==== Process Supplementary Service Response Direction: EUSE / HLR => MSC @@ -634,6 +667,7 @@ The purpose of this message is not clear yet. Probably, it can be used to notify the MSC that a structured supplementary service is successfully activated or deactivated, etc. +[[gsup-msg-mo-forwardsm-req]] ==== MO-forwardSM Request Direction: MSC / SGSN => SMSC (via HLR) @@ -653,6 +687,7 @@ This message is used to forward MO short messages from MSC / SGSN to an SMSC. The corresponding MAP service is MAP-MO-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.2. +[[gsup-msg-mo-forwardsm-err]] ==== MO-forwardSM Error Direction: SMSC (via HLR) => MSC / SGSN @@ -671,6 +706,7 @@ This message is used to indicate a negative result of an earlier MO short message delivery. The corresponding MAP service is MAP-MO-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.2. +[[gsup-msg-mo-forwardsm-res]] ==== MO-forwardSM Result Direction: SMSC (via HLR) => MSC / SGSN @@ -687,6 +723,7 @@ This message is used to indicate a successful result of an earlier MO short message delivery. The corresponding MAP service is MAP-MO-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.2. +[[gsup-msg-mt-forwardsm-req]] ==== MT-forwardSM Request Direction: SMSC (via HLR) => MSC / SGSN @@ -707,6 +744,7 @@ This message is used to forward MT short messages from an SMSC to MSC / SGSN. The corresponding MAP service is MAP-MT-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.9. +[[gsup-msg-mt-forwardsm-err]] ==== MT-forwardSM Error Direction: MSC / SGSN => SMSC (via HLR) @@ -725,6 +763,7 @@ This message is used to indicate a negative result of an earlier MT short message delivery. The corresponding MAP service is MAP-MT-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.9. +[[gsup-msg-mt-forwardsm-res]] ==== MT-forwardSM Result Direction: MSC / SGSN => SMSC (via HLR) @@ -741,6 +780,7 @@ This message is used to indicate a successful result of an earlier MT short message delivery. The corresponding MAP service is MAP-MT-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.9. +[[gsup-msg-ready-for-sm-req]] ==== READY-FOR-SM Request Direction: MSC / SGSN => SMSC (via HLR) @@ -759,6 +799,7 @@ indicates memory available situation (see TS GSM 04.11, section 7.3.2). The corresponding MAP service is MAP-READY-FOR-SM, see 3GPP TS 29.002, section 12.4. +[[gsup-msg-ready-for-sm-err]] ==== READY-FOR-SM Error Direction: SMSC (via HLR) => MSC / SGSN @@ -777,6 +818,7 @@ This message is used to indicate a negative result of an earlier MO SMMA (Memory Available) indication. The corresponding MAP service is MAP-READY-FOR-SM, see 3GPP TS 29.002, section 12.4. +[[gsup-msg-ready-for-sm-res]] ==== READY-FOR-SM Result Direction: SMSC (via HLR) => MSC / SGSN @@ -793,6 +835,7 @@ This message is used to indicate a successful result of an earlier MO SMMA (Memory Available) indication. The corresponding MAP service is MAP-READY-FOR-SM, see 3GPP TS 29.002, section 12.4. +[[gsup-msg-check-imei-req]] ==== CHECK-IMEI Request Direction: VLR => EIR (via HLR) @@ -805,6 +848,7 @@ Direction: VLR => EIR (via HLR) |50|IMEI|<<gsup-ie-imei>>|M|TLV|11 |=== +[[gsup-msg-check-imei-err]] ==== CHECK-IMEI Error Direction: EIR (via HLR) => VLR @@ -817,6 +861,7 @@ Direction: EIR (via HLR) => VLR |02|Cause|<<gsup-ie-cause>>|M|TLV|3 |=== +[[gsup-msg-check-imei-res]] ==== CHECK-IMEI Result Direction: EIR (via HLR) => VLR @@ -829,6 +874,7 @@ Direction: EIR (via HLR) => VLR |51|IMEI Check Result|<<gsup-ie-imei-result>>|M|TLV|3 |=== +[[gsup-msg-e-prep-ho-req]] ==== E Prepare Handover Request Direction: MSC-A=MSC-I => MSC-B=MSC-T (via HLR) @@ -844,6 +890,7 @@ Direction: MSC-A=MSC-I => MSC-B=MSC-T (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-prep-ho-err]] ==== E Prepare Handover Error Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) @@ -859,6 +906,7 @@ Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-prep-ho-res]] ==== E Prepare Handover Result Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) @@ -874,6 +922,7 @@ Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-prep-subs-ho-req]] ==== E Prepare Subsequent Handover Request Direction: MSC-B=MSC-I => MSC-A (via HLR) @@ -889,6 +938,7 @@ Direction: MSC-B=MSC-I => MSC-A (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-prep-subs-ho-err]] ==== E Prepare Subsequent Handover Error Direction: MSC-A => MSC-B=MSC-I (via HLR) @@ -904,6 +954,7 @@ Direction: MSC-A => MSC-B=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-prep-subs-ho-res]] ==== E Prepare Subsequent Handover Result Direction: MSC-A => MSC-B=MSC-I (via HLR) @@ -919,6 +970,7 @@ Direction: MSC-A => MSC-B=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-snd-end-sig-req]] ==== E Send End Signal Request Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) @@ -934,6 +986,7 @@ Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-snd-end-sig-err]] ==== E Send End Signal Error Direction: MSC-A=MSC-I => MSC-B=MSC-T (via HLR) @@ -949,6 +1002,7 @@ Direction: MSC-A=MSC-I => MSC-B=MSC-T (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-snd-end-sig-res]] ==== E Send End Signal Result Direction: MSC-A => MSC-B=MSC-I (via HLR) @@ -964,6 +1018,7 @@ Direction: MSC-A => MSC-B=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-proc-acc-sig-req]] ==== E Process Access Signalling Request Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) @@ -979,6 +1034,7 @@ Direction: MSC-B=MSC-T => MSC-A=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-forw-acc-sig-req]] ==== E Forward Access Signalling Request Direction: MSC-A => MSC-B=MSC-I (via HLR) @@ -994,6 +1050,7 @@ Direction: MSC-A => MSC-B=MSC-I (via HLR) |62|AN-APDU|<<gsup-ie-an-apdu>>|M|TLV|2-... |=== +[[gsup-msg-e-close]] ==== E Close Direction: MSC-A => MSC-B (via HLR) @@ -1008,11 +1065,13 @@ Direction: MSC-A => MSC-B (via HLR) |61|Destination Name|<<gsup-ie-destination-name>>|M|TLV|2-... |=== +[[gsup-msg-e-abort]] ==== E Abort This message was added to GSUP for the inter-MSC handover. But so far it is not used yet. +[[gsup-msg-e-routing-err]] ==== E Routing Error Direction: GSUP Server (HLR) => GSUP Client (MSC) @@ -1029,6 +1088,53 @@ Direction: GSUP Server (HLR) => GSUP Client (MSC) |31|Session State|<<gsup-ie-session-state>>|O|TLV|3 |=== +[[gsup-msg-epdg-tunnel-req]] +==== ePDG Tunnel Request + +Direction: GSUP Client (strongswan) => GSUP Server (ePDG) + +[options="header",cols="5%,45%,20%,10%,10%,10%"] +|=== +|IEI|IE|Type|Presence|Format|Length +| |Message Type|<<gsup-ie-msgtype>>|M|V|1 +|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10 +|0a|Message Class|<<gsup-ie-message-class>>|M|TLV|3 +|15|PCO|<<gsup-ie-pco>>|O|TLV|1-... +|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 +|60|Source Name|<<gsup-ie-source-name>>|O|TLV|2-... +|=== + +[[gsup-msg-epdg-tunnel-err]] +==== ePDG Tunnel Error + +Direction: GSUP Server (ePDG) => GSUP Client (strongswan) + +[options="header",cols="5%,45%,20%,10%,10%,10%"] +|=== +|IEI|IE|Type|Presence|Format|Length +| |Message Type|<<gsup-ie-msgtype>>|M|V|1 +|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10 +|0a|Message Class|<<gsup-ie-message-class>>|M|TLV|3 +|02|Cause|<<gsup-ie-cause>>|M|TLV|3 +|=== + +[[gsup-msg-epdg-tunnel-res]] +==== ePDG Tunnel Result + +Direction: GSUP Server (ePDG) => GSUP Client (strongswan) + +[options="header",cols="5%,45%,20%,10%,10%,10%"] +|=== +|IEI|IE|Type|Presence|Format|Length +| |Message Type|<<gsup-ie-msgtype>>|M|V|1 +|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10 +|0a|Message Class|<<gsup-ie-message-class>>|M|TLV|3 +|04|PDP info complete|<<gsup-ie-empty>>|M|TLV|2 +|05|PDP info|<<gsup-ie-pdpinfo>>|M|TLV|2-N +|15|PCO|<<gsup-ie-pco>>|O|TLV|1-... +|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3 +|60|Source Name|<<gsup-ie-source-name>>|O|TLV|2-... +|=== === Information Elements @@ -1037,41 +1143,58 @@ Direction: GSUP Server (HLR) => GSUP Client (MSC) [options="header",cols="10%,90%"] |=== -|Type|Description -|0x04|Update Location Request -|0x05|Update Location Error -|0x06|Update Location Result -|0x08|Send Auth Info Request -|0x09|Send Auth Info Error -|0x0a|Send Auth Info Result -|0x0b|Authentication Failure Report -|0x0c|Purge MS Request -|0x0d|Purge MS Error -|0x0e|Purge MS Result -|0x10|Insert Subscriber Data Request -|0x11|Insert Subscriber Data Error -|0x12|Insert Subscriber Data Result -|0x14|Delete Subscriber Data Request -|0x15|Delete Subscriber Data Error -|0x16|Delete Subscriber Data Result -|0x1c|Location Cancellation Request -|0x1d|Location Cancellation Error -|0x1e|Location Cancellation Result -|0x20|Supplementary Service Request -|0x21|Supplementary Service Error -|0x22|Supplementary Service Result -|0x24|MO-forwardSM Request -|0x25|MO-forwardSM Error -|0x26|MO-forwardSM Result -|0x28|MT-forwardSM Request -|0x29|MT-forwardSM Error -|0x2a|MT-forwardSM Result -|0x2c|READY-FOR-SM Request -|0x2d|READY-FOR-SM Error -|0x2e|READY-FOR-SM Result -|0x30|CHECK-IMEI Request -|0x31|CHECK-IMEI Error -|0x32|CHECK-IMEI Result +|Type|Name|Description +|0x04|Update Location Request|<<gsup-msg-upd-loc-req>> +|0x05|Update Location Error|<<gsup-msg-upd-loc-err>> +|0x06|Update Location Result|<<gsup-msg-upd-loc-res>> +|0x08|Send Authentication Info Request|<<gsup-msg-auth-info-req>> +|0x09|Send Authentication Info Error|<<gsup-msg-auth-info-err>> +|0x0a|Send Authentication Info Result|<<gsup-msg-auth-info-res>> +|0x0b|Authentication Failure Report|<<gsup-msg-auth-fail-rep>> +|0x0c|Purge MS Request|<<gsup-msg-purge-ms-reqs>> +|0x0d|Purge MS Error|<<gsup-msg-purge-ms-err>> +|0x0e|Purge MS Result|<<gsup-msg-purge-ms-res>> +|0x10|Insert Subscriber Data Request|<<gsup-msg-ins-sub-req>> +|0x11|Insert Subscriber Data Error|<<gsup-msg-ins-sub-err>> +|0x12|Insert Subscriber Data Result|<<gsup-msg-ins-sub-res>> +|0x14|Delete Subscriber Data Request|<<gsup-msg-del-sub-req>> +|0x15|Delete Subscriber Data Error|<<gsup-msg-del-sub-err>> +|0x16|Delete Subscriber Data Result|<<gsup-msg-del-sub-res>> +|0x1c|Location Cancellation Request|<<gsup-msg-loc-cancel-req>> +|0x1d|Location Cancellation Error|<<gsup-msg-loc-cancel-err>> +|0x1e|Location Cancellation Result|<<gsup-msg-loc-cancel-res>> +|0x20|Supplementary Service Request|<<gsup-msg-proc-supl-serv-req>> +|0x21|Supplementary Service Error|<<gsup-msg-proc-supl-serv-err>> +|0x22|Supplementary Service Result|<<gsup-msg-proc-supl-serv-res>> +|0x24|MO-forwardSM Request|<<gsup-msg-mo-forwardsm-req>> +|0x25|MO-forwardSM Error|<<gsup-msg-mo-forwardsm-err>> +|0x26|MO-forwardSM Result|<<gsup-msg-mo-forwardsm-res>> +|0x28|MT-forwardSM Request|<<gsup-msg-mt-forwardsm-req>> +|0x29|MT-forwardSM Error|<<gsup-msg-mt-forwardsm-err>> +|0x2a|MT-forwardSM Result|<<gsup-msg-mt-forwardsm-res>> +|0x2c|READY-FOR-SM Request|<<gsup-msg-ready-for-sm-req>> +|0x2d|READY-FOR-SM Error|<<gsup-msg-ready-for-sm-err>> +|0x2e|READY-FOR-SM Result|<<gsup-msg-ready-for-sm-res>> +|0x30|CHECK-IMEI Request|<<gsup-msg-check-imei-req>> +|0x31|CHECK-IMEI Error|<<gsup-msg-check-imei-err>> +|0x32|CHECK-IMEI Result|<<gsup-msg-check-imei-res>> +|0x34|E Prepare Handover Request|<<gsup-msg-e-prep-ho-req>> +|0x35|E Prepare Handover Error|<<gsup-msg-e-prep-ho-err>> +|0x36|E Prepare Handover Result|<<gsup-msg-e-prep-ho-res>> +|0x38|E Prepare Subsequent Handover Request|<<gsup-msg-e-prep-subs-ho-req>> +|0x39|E Prepare Subsequent Handover Error|<<gsup-msg-e-prep-subs-ho-err>> +|0x3a|E Prepare Subsequent Handover Result|<<gsup-msg-e-prep-subs-ho-res>> +|0x3c|E Send End Signal Request|<<gsup-msg-e-snd-end-sig-req>> +|0x3d|E Send End Signal Error|<<gsup-msg-e-snd-end-sig-err>> +|0x3e|E Send End Signal Result|<<gsup-msg-e-snd-end-sig-res>> +|0x40|E Process Access Signalling Request|<<gsup-msg-e-proc-acc-sig-req>> +|0x44|E Forward Access Signalling Request|<<gsup-msg-e-forw-acc-sig-req>> +|0x47|E Close|<<gsup-msg-e-close>> +|0x4B|E Abort|<<gsup-msg-e-abort>> +|0x4E|E Routing Error|<<gsup-msg-e-routing-err>> +|0x50|ePDG Tunnel Request|<<gsup-msg-epdg-tunnel-req>> +|0x51|ePDG Tunnel Error|<<gsup-msg-epdg-tunnel-err>> +|0x52|ePDG Tunnel Result|<<gsup-msg-epdg-tunnel-res>> |=== The category of the message is indicated by the last two bits of the type. @@ -1091,7 +1214,7 @@ trivial to transform them. ==== IP Address The value part is encoded like in the Packet data protocol address IE defined -in 3GPP TS 04.08, Chapter 10.5.6.4. PDP type organization must be set to +in 3GPP TS 24.008, Chapter 10.5.6.4. PDP type organization must be set to 'IETF allocated address'. [[gsup-ie-pdpinfo]] @@ -1105,7 +1228,7 @@ This is a container for information elements describing a single PDP. | |PDP Info IEI|<<gsup-iei>>|M|V|1 | |Length of PDP Info IE||M|V|1 |10|PDP Context ID|<<gsup-ie-pdpctxid>>|C|TLV|3 -|11|PDP Type|<<gsup-ie-pdptype>>|C|TLV|4 +|11|PDP Address|<<gsup-ie-pdpaddress>>|C|TLV|4-24 |12|Access Point Name|<<gsup-ie-apn>>|C|TLV|3-102 |13|Quality of Service|<<gsup-ie-qos>>|O|TLV|1-20 |14|PDP-Charging Characteristics|<<gsup-ie-charging>>|O|TLV|4 @@ -1113,11 +1236,14 @@ This is a container for information elements describing a single PDP. The conditional IE are mandantory unless mentioned otherwise. -[[gsup-ie-pdptype]] -==== PDP Type +[[gsup-ie-pdpaddress]] +==== PDP Address -The PDP type value consists of 2 octets that are encoded like octet 4-5 of the -End User Address defined in 3GPP TS 09.60, 7.9.18. +The value part is encoded like in the Packet data protocol address IE defined +in 3GPP TS 24.008, Chapter 10.5.6.4. +Hence this value also relates to End User Address (EUA) IE defined in 3GPP TS +29.060, 7.7.27. +The PDP type organization value must be set to 'IETF allocated address'. [packetdiag] ---- @@ -1127,21 +1253,24 @@ End User Address defined in 3GPP TS 09.60, 7.9.18. 0-6: PDP type IEI 7: Res - 8-15: Length (2) - 16-19: Spare - 20-23: PDP type org + 8-15: Length + 16-19: PDP type org + 20-23: Spare 24-31: PDP type number + 32-191: Address (v4|v6|v4+v6) } ---- -The spare bits are left undefined. While 09.60 defines them as '1 1 1 1', there -are MAP traces where these bits are set to '0 0 0 0'. So the receiver shall -ignore these bits. +The spare bits are left undefined. While 3GPP TS 29.060 7.7.27 defines them as +'1 1 1 1', there are MAP traces where these bits are set to '0 0 0 0'. So the +receiver shall ignore these bits. Examples: -* IPv4: PDP type org: 1 (IETF), PDP type number: 0x21 -* IPv6: PDP type org: 1 (IETF), PDP type number: 0x57 +* IPv4: PDP type org: 1 (IETF), PDP type number: 0x21, 0 bytes address (dynamic addressing) +* IPv4: PDP type org: 1 (IETF), PDP type number: 0x21, 4 bytes address +* IPv6: PDP type org: 1 (IETF), PDP type number: 0x57, 16 bytes address +* IPv6: PDP type org: 1 (IETF), PDP type number: 0x8D, 20 bytes address (v4+v6) [[gsup-ie-pdpctxid]] ==== PDP Context ID @@ -1285,7 +1414,7 @@ IEI that shall be used for the encoding. [options="header",cols="15%,35%,50%"] |=== |IEI|Info Element|Type / Encoding -|0x01|IMSI|Mobile Identity, 3GPP TS 04.08 Ch. 10.5.1.4 +|0x01|IMSI|Mobile Identity, 3GPP TS 24.008 Ch. 10.5.1.4 |0x02|Cause|<<gsup-ie-cause>> |0x03|Auth Tuple|<<gsup-ie-authtuple>> |0x04|PDP Info Compl|<<gsup-ie-empty>> @@ -1296,10 +1425,11 @@ IEI that shall be used for the encoding. |0x09|HLR Number|<<gsup-ie-hlr>> |0x0a|Message Class| <<gsup-ie-message-class>> |0x10|PDP Context ID|<<gsup-ie-pdpctxid>> -|0x11|PDP Type|<<gsup-ie-pdptype>> +|0x11|PDP Address|<<gsup-ie-pdptaddress>> |0x12|Access Point Name|<<gsup-ie-apn>> |0x13|QoS|<<gsup-ie-qos>> |0x14|PDP-Charging Characteristics|<<gsup-ie-charging>> +|0x15|PCO|<<gsup-ie-pco>> |0x20|RAND|<<gsup-ie-rand>> |0x21|SRES|<<gsup-ie-sres>> |0x22|Kc|<<gsup-ie-kc>> @@ -1351,7 +1481,7 @@ The semantics depend on the IEI and the context. ==== IMSI The IMSI is encoded like in octet 4-N of the Called Party BCD Number -defined in 3GPP TS 04.08, 10.5.4.7. +defined in 3GPP TS 24.008, 10.5.4.7. [packetdiag] ---- @@ -1377,7 +1507,7 @@ Number digit N-1' (N even), where N is the number of digits. ==== ISDN-AddressString / MSISDN / Called Party BCD Number The MSISDN is encoded as an ISDN-AddressString in 3GPP TS 09.02 and Called Party -BCD Number in 3GPP TS 04.08. It will be stored by the SGSN or VLR and then passed as is +BCD Number in 3GPP TS 24.008. It will be stored by the SGSN or VLR and then passed as is to the GGSN during the activation of the primary PDP Context. [packetdiag] @@ -1413,7 +1543,7 @@ SGSN during the PDP Context activation. If the length of the QoS data is 3 (three) octets it is assumed that these are octets 3-5 of the TS 3GPP TS 24.008 Quality of Service Octets. If it is more than three then then it is assumed that the first octet is the Allocation/Retention -Priority and the reset are encoded as octets 3-N of 24.008. +Priority and the rest are encoded as octets 3-N of 24.008. [packetdiag] ---- @@ -1448,6 +1578,12 @@ used by the SGSN or VLR when activating a PDP context. } ---- +[[gsup-ie-pco]] +==== Protocol Configuration Options (PCO) + +This encodes the Protocol Configuration Options (PCO) of 3GPP TS 29.060 clause +7.7.31, which are the same as those specified in 3GPP TS 24.008 10.5.6.3. It +will be used by the ePDG during the PDP Context activation. [[gsup-ie-hlr]] ==== HLR Number encoded as 3GPP TS 09.02 ISDN-AddressString @@ -1479,7 +1615,7 @@ record. ==== Cause This IE shall be encoded according to the 'GMM Cause' as described in -Chapter 10.5.5.14 of 3GPP TS 04.08. +Chapter 10.5.5.14 of 3GPP TS 24.008. [[gsup-ie-ss-info]] ==== Supplementary Service Info @@ -1491,7 +1627,7 @@ of Supplementary Services encoded according to GSM TS 04.80. [[gsup-ie-imei]] ==== IMEI -The IMEI encoded as Called Party BCD Number in 3GPP TS 04.08. +The IMEI encoded as Called Party BCD Number in 3GPP TS 24.008. [[gsup-ie-imei-result]] ==== IMEI Check Result diff --git a/common/chapters/installation.adoc b/common/chapters/installation.adoc new file mode 100644 index 0000000..55b7e60 --- /dev/null +++ b/common/chapters/installation.adoc @@ -0,0 +1,68 @@ +== Installation + +This section is a general section providing a high-level overview how to +install Osmocom software on your GNU/Linux system. + +It is important that you choose one of the options outlined below. +Trying to mix some packages from a distribution with some packages from +osmocom.org while building some other parts from source is likely asking +for troubles that could be avoided if you stick to all osmocom software +from either one of those sources, without mixing + matching. + +=== Official Osmocom Binary Packages + +The Osmocom project packages most of its software as binary packages for +a variety of GNU/Linux distributions, both in `rpm` and `dpkg` package +formats. + +For the most up-to-date information, please check out the related wiki +page at https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages + +At the time of this writing there are two main flavours: + +* the `latest` feed (containing the latest tagged version of each + program). See https://osmocom.org/projects/cellular-infrastructure/wiki/Latest_Builds +* the `nightly` feed (containing automatic nightly builds of each + program). See https://osmocom.org/projects/cellular-infrastructure/wiki/Nightly_Builds + +=== Distribution Binary Packages + +Your GNU/Linux distribution may contain packages of Osmocom software. If you use those +packages, please look for any distributions-specific information on how those packages +might deviate from upstream, such as for example on Debian GNU/Linux the files located in +`/usr/share/doc/osmo-*/README.Debian`. + +Please note that Distribution packages usually lag behind the official +_upstream_ packages the Osmocom project releases. It is a matter of +personal preference or policy which packages you use. + + +=== Building from source code + +All of Osmocom is Open Source software, so of course the full source +code of the related software is released, and you are free to download, +build, explore it and hack on it. + +The official location for all osmocom source code is at https://gitea.osmocom.org/ + +However, if you are just a normal user and not a developer familiar with +classic C development on GNU/Linux, we *strongly recommend* you to use +some of the binary package options indicated above. + +If you know your way around git, make, autotools, pkg-config, etc. by all +means, go ahead, don't be discouraged. We just want to avoid normal +users from having to work with unfamiliar tools and wasting time on +getting software to build, rather than actually using it. + +Some general (possibly outdated) instructions on how to build Osmocom +software from source can be found at +https://osmocom.org/projects/cellular-infrastructure/wiki/Build_from_Source + +In general, the usual approach is to + +* start with `libosmocore` and all the required libraries and build + them in order until you have the full chain of dependencies in place. + As a final step, build the actual application you want to use. +* perform `autoreconf -fi`, `./configure` and `make install` for each of + the projects. Check the `./configure --help` output to see which + optional compile-time features you might want to enable or disable. diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc index b0a1f5e..0b31211 100644 --- a/common/chapters/logging.adoc +++ b/common/chapters/logging.adoc @@ -32,7 +32,7 @@ Each sub-system of the program in question typically logs its messages as a different category, allowing fine-grained control over which log messages you will or will not see. For example, in OsmoBSC, there are categories for the protocol layers `rsl`, `rr`, `mm`, -`cc` and many others. To get a a list of categories interactively +`cc` and many others. To get a list of categories interactively on the vty, type: `logging level ?` [[log_levels]] @@ -200,9 +200,16 @@ the incoming log messages will push out the oldest messages available in the buf ==== Logging via gsmtap -When debugging complex issues it's handy to be able to reconstruct exact chain of events. This is enabled by using GSMTAP -log output where frames sent/received over the air are intersperced with the log lines. It also simplifies the bug handling -as users don't have to provide separate .pcap and .log files anymore - everything will be inside self-contained packet dump. +GSMTAP is normally a pseudo-header format that enables the IP-transport of GSM (or other telecom) protocols +that are not normally transported over IP. For example, the most common situation is to enable GSMTAP in +OsmoBTS or OsmoPCU to provide GSM-Um air interface capture files over IP, so they can be analyzed in +wireshark. + +GSMTAP logging is now a method how Osmocom software can also encapsulate its own log output in GSMTAP frames. +We're not trying to re-invent rsyslog here, but this is very handy When debugging complex issues. It enables +the reader of the pcap file containing GSMTAP logging together with other protocol traces to reconstruct exact +chain of events. A single pcap file can then contain both the log output of any number of Osmocom programs in +the same timeline of the messages on various interfaces in and out of said Osmocom programs. It's configured as follows: ---- @@ -230,6 +237,15 @@ OsmoBSC(config)# log stderr OsmoBSC(config-log)# logging level force-all fatal ---- +NOTE: Every time you generate GSMTAP messages and send it to a unicast (non-broadcast/multicast) IP address, +please make sure that the destination IP address actually has a socket open on the specified port, or drops +the packets in its packet filter. If unicast GSMTAP messages arrive at a closed destination UDP port, the +operating system will likely generate ICMP port unreachable messages. Those ICMP messages in turn will, when +arriving at the source (the host on which you run the Osmocom software sending GSMTAP), suppress generation +of further GSMTAP messages for some time, resulting in incomplete files. In case of doubt, either send GSMTAP +to multicast IP addresses, or run something like `nc -l -u -p 4729 > /dev/null` on the destination host to +open the socket at the GSMTAP port and discard anything arriving at it. + ==== Logging to a file As opposed to Logging to the VTY, logging to files is persistent and diff --git a/common/chapters/mgwpool.adoc b/common/chapters/mgwpool.adoc new file mode 100644 index 0000000..afb0d2b --- /dev/null +++ b/common/chapters/mgwpool.adoc @@ -0,0 +1,284 @@ +[[mgw_pooling]] +== MGW Pooling + +{program-name} is able to use a pool of media gateway (MGW) instances. +The aim of MGW pooling is to evenly distribute the RTP voice stream load across +multiple MGW instances. This can help to scale out over multiple VMs or physical +machines. Until osmo-mgw includes multithreading support, it may also be used to +scale-out to multiple cores on a single host. + +The load distribution is managed in such a way that when a new call is placed, +the pool will automatically assign the call to the available MGW with the lowest load. + +MGW pooling is recommended for larger RAN or CN installations. For small networks +and lab installations the classic method with one MGW per {program-name} offers +sufficient performance. + +=== MGW pool VTY configuration + +In {program-name} the MGW is controlled via an MGCP-Client. The VTY commands to +configure the MGCP-Client are part of the several 'mgw' nodes, one per +MGCP-Client to set up. + +To setup an MGW pool, the user must first install multiple OsmoMGW instances, so +that they won’t interfere with each other. This can be done using different +local host IP addresses or different ports. When OsmoMGW is installed from +packages, the systemd configuration may also require adjustment. + +By default, MGCP-Client will use whatever source IP address is resolved by the +kernel routing subsystem, and will also ask the kernel to pick a free UDP port. + +Example configuration with two MGCP-Client instances in a pool: +---- + mgw 0 + description media-gw-0 <2> + remote-ip 127.0.0.1 + remote-port 2432 + local-ip 127.0.0.1 + local-port 2431 + endpoint-domain mgw0 <1> + mgw 1 + description media-gw-1 <2> + remote-ip 127.0.0.1 + remote-port 2430 + local-ip 127.0.0.1 + local-port 2429 + endpoint-domain mgw1 <1> +---- + +<1> When working with multiple MGW / MGCP-Client instances, the domain name for +each MGW should be different. Otherwise it won't be possible to distinguish the +endpoint names in the log. It should also be noted that the domain name must +match the configuration of the related OsmoMGW instance. + +<2> It is also possible to assign a descriptive name to each MGW instance. The +MGCP client specific log lines will then use this name as logging context. If +no description is set, the domain name will be used. + +=== MGW pool management + +The MGW pool is fully runtime-manageable. The only limitation +is that an MGCP-Client can not be restarted or removed as long as it is serving +calls (see also: <<mgw_pooling_blocking>>). + +==== MGW pool status + +The VTY implements a 'show mgw-pool' command that lists the currently configured +MGW pool members, their status and call utilization. The following snippet shows +an output example run on OsmoBSC, but it should be also available on other +applications supporting the MGW pooling VTY features: + +---- +OsmoBSC> show mgw-pool +% MGW-Pool: +% MGW 0:media-gw-0 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 1 +% MGW 1:media-gw-1 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 0 +---- + +==== Adding an MGW / MGCP-Client to the MGW pool + +To add a new MGCP-Client to the pool, the 'mgw' node is used. Like with the +'bts' or the 'msc' node a reference number is used that usually starts at 0. +However it is still possible to assign any number from 0-255. The enumeration +also may contain gaps. The following snippet shows an output example run on +OsmoBSC, but it should be also available on other applications supporting the +MGW pooling VTY features: + +---- +OsmoBSC> enable +OsmoBSC# configure terminal +OsmoBSC(config)# network +OsmoBSC(config-net)# mgw 2 +OsmoBSC(config-mgw)# ? + keepalive Monitor if the MGCP link against MGW is still usable + local-ip local bind to connect to MGW from + local-port local port to connect to MGW from + remote-ip remote IP address to reach the MGW at + remote-port remote port to reach the MGW at + endpoint-domain Set the domain name to send in MGCP messages, e.g. the part 'foo' in 'rtpbridge/*@foo'. + reset-endpoint Add an endpoint name that should be reset (DLCX) on connect to the reset-endpoint list,e.g. 'rtpbridge/*' +---- + +The newly added MGW will immediately appear in the mgw-pool list but it won't +be used until its configuration finished by reconnecting it. + +---- +% MGW-Pool: +% MGW 0:media-gw-0 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 2 +% MGW 1:media-gw-1 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 3 +% MGW 2:mgw <1> +% MGCP link: disconnected,DOWN +% service: unblocked +% ongoing calls: 0 +---- + +<1> In this example a description is not set yet, so the domain name ("mgw") +is displayed. + +==== Reconnecting an MGW / MGCP-Client + +It may become necessary to reconnect an MGCP-Client. This is the case when the +VTY configuration was changed at runtime. In order to make the changes effective +the MGW configuration must be reloaded by reconnecting the MGW connection. Also +newly created MGW instances require a reconnect once their configuration is +done. + +To reconnect an MGCP-Client use the 'reconnect' VTY command: +---- +OsmoBSC# mgw 2 reconnect +---- + +The mgcp-client status should immediately change to 'connected'. The MGW is now +ready to be used for new calls. + +---- +OsmoBSC# show mgw-pool +% MGW-Pool: +% MGW 0:media-gw-0 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 2 +% MGW 1:media-gw-1 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 3 +% MGW 2:mgw +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 0 +---- + +It should be noted that MGCP a protocol is used via UDP, the connect only +happens locally to forward the UDP datagrams properly (state printed in +`mgcp-client: (dis)connected` above). Also (unless a reset endpoint is +configured like in the example config above) there will be no immediate +interaction with the MGW. However, the log should at least confirm the connect +worked and the MGCP client has been created successfully. + +---- +Mon Aug 2 17:15:00 2021 DLMGCP mgcp_client.c:788 MGCP client: using endpoint domain '@mgw' +Mon Aug 2 17:15:00 2021 DLMGCP mgcp_client.c:908 MGCP GW connection: r=127.0.0.1:2427<->l=127.0.0.1:2727 +---- + +For that reason, it is strongly advised to enable the `keepalive` feature in +{program-name} to schedule periodical MGCP queries against the MGW, in order to +make sure it is reachable (the state `MGCP link: UP|DOWN` printed above). See +section <<mgw_pooling_keepalive>> below for more information. + +[[mgw_pooling_keepalive]] +==== Monitor MGCP link (keepalive) / MGCP-Client + +The `keepalive` feature in {program-name} allows scheduling periodical queries +on the MGCP layer in order to make sure it is reachable and hence obtain +information on the state of the MGCP link. This is in turn used by the MGW Pool +when picking an MGW from the pool: MGWs whose link is considered to be DOWN are +skipped. + +The feature consists of: +- A `keepalive request-interval` which will trigger a transmission of an MGCP +AuditEndpoint command targeting endpoint with name `keepalive request-endpoint`. +This interval is updated every time any message is transmitted in the MGCP link, +meaning the MGCP AuditEndpoint message is only triggered if no message has been +transmitted since `keepalive request-interval` seconds ago. +- A `keepalive timeout` which upon triggering (because no message was received +over that amount of time) will then consider the MGW to be non-reachable (link +DOWN). + +The `keepalive` parameters are to be preferrably configured so that +`"keepalive request-interval" * 2 < "keepalive timeout"`. + +Example VTY configuration of `keepalive` feature in {program-name}: +---- + mgw 0 + ... + keepalive request-interval 20 <1> + keepalive request-endpoint null <2> + keepalive timeout 50 <3> +---- + +<1> Transmit an MGCP AuditEndpoint message to the MGW if no message has been +sent to it over last 20 seconds +<2> The MGCP AuditEndpoint targets the `null` endpoint. This is a special +endpoint available at OsmoMGW for those purposes, but any available endpoint can +be configured and used instead. +<3> Consider the MGCP link to be DOWN if no message is received from the MGW +over the last 50 seconds + +NOTE: The `keepalive` feature is disabled by default, and must be explicitly +configured in order to enable it. + +[[mgw_pooling_blocking]] +==== Blocking an MGW / MGCP-Client + +If it becomes apparent that an MGCP-Client must be restarted or removed from +the config (maintenance) the operator can put that MGCP-Client into a blocked +mode. A blocked MGCP-Client will still serve the ongoing calls but it will not +be picked for the assignment of new calls. + +To block an MGCP-Client use the 'block' VTY command: +---- +OsmoBSC# mgw 2 block +OsmoBSC# show mgw-pool +% MGW-Pool: +% MGW 0:media-gw-0 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 11 +% MGW 1:media-gw-1 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 12 +% MGW 2:mgw +% MGCP link: connected,UP +% service: blocked +% ongoing calls: 10 +---- + +When the number of ongoing calls has tapered off, the MGW / MGCP-Client can be +restarted or removed if necessary. + +---- +OsmoBSC# show mgw-pool +% MGW-Pool: +% MGW 0:media-gw-0 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 15 +% MGW 1:media-gw-1 +% MGCP link: connected,UP +% service: unblocked +% ongoing calls: 14 +% MGW 2:mgw +% MGCP link: connected,UP +% service: blocked +% ongoing calls: 0 +---- + +If the blockade should be reverted, the 'unblock' VTY command can be used in +the same way to remove the blockade. (Reconnecting will not remove the +blockade.) + +==== Removing an MGW / MGCP-Client + +An MGCP-Client is removed from the pool using the 'no mgw' command from the +configure terminal. The MGCP-Client instance will automatically be terminated +and the related resources are freed. The only requirement is that there are no +ongoing calls on the selected instance. + +---- +OsmoBSC# configure terminal +OsmoBSC(config)# network +OsmoBSC(config-net)# no mgw 2 +---- diff --git a/common/chapters/mncc.adoc b/common/chapters/mncc.adoc index 15c9982..e897294 100644 --- a/common/chapters/mncc.adoc +++ b/common/chapters/mncc.adoc @@ -53,12 +53,14 @@ any internal call switching, but delegate all call-control handling towards the external MNCC program connected via the MNCC socket. If you intend to operate {program-name} with external MNCC handler, you have -to start it with the `-m` or `--mncc-sock` command line option. +to disable the internal MNCC handler and specify the MNCC socket path in +the configuration file. -At the time of this writing, the only external application implementing the -MNCC interface compatible with the Osmocom MNCC socket is `lcr`, the Linux Call -Router. More widespread integration of external call routing is available via -the OsmoSIPConnector. +At the time of this writing, there are only two known open source applications implementing the +MNCC interface compatible with the Osmocom MNCC socket: + +* historically `lcr`, the Linux Call Router (support for modern MNCC protocol versions may be missing) +* `osmo-sip-connector`, the more up-to-date integration of external call routing by translating MNCC into a SIP trunk towards an external SIP PBX / switch. === DTMF considerations diff --git a/common/chapters/oap.adoc b/common/chapters/oap.adoc index ad91f36..5255b4a 100644 --- a/common/chapters/oap.adoc +++ b/common/chapters/oap.adoc @@ -81,7 +81,7 @@ When the client has received a Challenge, it may verify the server's authenticity and validity of the sequence number (included in AUTN), and, if valid, reply with a CHALLENGE_RES message. This shall contain an XRES authentication token generated by milenage from the same random bytes received -from the server and the same shared secet. If the client decides to cancel the +from the server and the same shared secret. If the client decides to cancel the registration (e.g. invalid AUTN), it shall not reply to the CHALLENGE_REQ; a CHALLENGE_ERR message may be sent, but is not mandatory. For example, the client may directly start with a new REGISTER_REQ message. @@ -136,7 +136,7 @@ Direction: Server -> Client |=== |IEI|IE|Type|Presence|Format|Length | |Message Type|<<common-oap-ie-msgtype>>|M|V|1 -|02|Cause|GMM Cause, TS 04.08: 10.5.5.14|M|TLV|3 +|02|Cause|GMM Cause, TS 24.008: 10.5.5.14|M|TLV|3 |=== ==== Register Result @@ -169,7 +169,7 @@ Direction: Client -> Server |=== |IEI|IE|Type|Presence|Format|Length | |Message Type|<<common-oap-ie-msgtype>>|M|V|1 -|02|Cause|GMM Cause, TS 04.08: 10.5.5.14|M|TLV|3 +|02|Cause|GMM Cause, TS 24.008: 10.5.5.14|M|TLV|3 |=== ==== Challenge Result diff --git a/common/chapters/osmux/mgcp_extension_osmux.adoc b/common/chapters/osmux/mgcp_extension_osmux.adoc index e2b0947..45e95e7 100644 --- a/common/chapters/osmux/mgcp_extension_osmux.adoc +++ b/common/chapters/osmux/mgcp_extension_osmux.adoc @@ -19,11 +19,11 @@ their respective response messages. In request messages, the value part of `X-Osmux` specifies the CID to be used by OsmoMGW to _send_ Osmux frames to the remote peer for that connection, also -known as _sendCID_. +known as the MGW's _remote CID_ or the peer's _local CID_. In response messages, the value part of `X-Osmux` specifies the CID where OsmoMGW expect to _receive_ Osmux frames from the remote peer for that -connection, also known as _recvCID_. +connection, also known as the MGW's _local CID_ or the peer's _remote CID_. .Example: `X-Osmux` format with a known CID 3. ---- @@ -39,12 +39,12 @@ X-Osmux: * If the MGCP client is willing to use Osmux for a given connection, it shall specify so during `CRCX` time, and not later. If at `CRCX` time the MGCP client -doesn't yet know the _sendCID_, it can use an astersik (*) and provide -_sendCID_ later within `MDCX` messages. +doesn't yet know the MGW's _remote CID_, it can use an astersik (*) and provide +_remote CID_ later within `MDCX` messages. All subsequent `MDCX` messages sent towards an Osmux connection must contain the -original _sendCID_ sent during `CRCX`. The same way, all `MDCX` response shall -contain the _recvCID_ sent during `CRCX`. +original MGW's _remote CID_ sent during `CRCX`. The same way, all `MDCX` response shall +contain the _local CID_ sent during `CRCX`. The other required connection address parameters, such as IP address, port, and codecs, are negotiated through MGCP and SDP as usual, but in this case the IP @@ -72,7 +72,7 @@ a=rtpmap:112 AMR/8000/1 a=ptime:20 ---- -.Example: response to `CRCX` containing the <<recvCID>> +.Example: response to `CRCX` containing the MGW's _local CID_ ---- 200 189 OK I: 07E41584 diff --git a/common/chapters/osmux/mo_call_osmux_abis.msc b/common/chapters/osmux/mo_call_osmux_abis.msc new file mode 100644 index 0000000..5c281a0 --- /dev/null +++ b/common/chapters/osmux/mo_call_osmux_abis.msc @@ -0,0 +1,54 @@ +# MO-call with Osmux enable on 3GPP AoIP +msc { + hscale=2; + ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"]; + + bsc <- m_sc [label="BSSMAP RESET (with extension IE: Osmux Support)"]; + bsc -> m_sc [label="BSSMAP RESET ACK (with extension IE: Osmux Support)"]; + ...; + ms box mgw_msc [label="We assume a SDCCH is already established"]; + ...; + + ms -> bsc [label="DTAP CM Service Request"]; + bsc -> m_sc [label="Complete Layer 3 Information DTAP CM Service Request"]; + + # Allocate MGW/MSC Osmux endpoint + m_sc -> mgw_msc [label="MGCP CRCX rtpbridge/*@mgw, X-Osmux: *"]; + mgw_msc box mgw_msc [label="Bind to MGW-local RTP Port (5000)\nAllocate new endpoint 1"]; + mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:5000)"]; + + bsc <- m_sc [label="BSSAP ASSGN REQ"]; + bts <- bsc [label="RSL CHAN ACT"]; + bts -> bsc [label="RSL CHAN ACT ACK"]; + ms <- bsc [label="Assignment Command"]; + ms -> bsc [label="Assignment Complete"]; + ...; + + # connect BTS RTP with BSC-MGW RTP + bsc -> mgw_bsc [label="MGCP CRCX rtpbridge/*@mgw, X-Osmux: *"]; + mgw_bsc box mgw_bsc [label="Bind to MGW-local Osmux Port (1984)\n\nAllocate new endpoint 2, MGW's local CID 5"]; + bsc <- mgw_bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:1984, X-Osmux: 5)"]; + bts <- bsc [label="IPA CRCX (Extension IE Osmux-CID 5)"]; + bts box bts [label="Bind to BTS-local Osmux Port (1985), Allocate new BTS's local CID 7"]; + bts -> bsc [label="IPA CRCX ACK (BTS:1985, Extension IE Osmux-CID 7)"]; + bsc -> mgw_bsc [label="MGCP MDCX rtpbridge/2@mgw (BTS:1985, X-Osmux: 7)"]; + mgw_bsc box mgw_bsc [label="\nConnect to BTS:1985 MGW's remote CID 7"]; + bsc <- mgw_bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:1984, X-Osmux: 5)"]; + ...; + + mgw_bsc <- bsc [label="MGCP CRCX rtpbridge/2@mgw (MSC:5000)"]; + mgw_bsc box mgw_bsc [label="Bind to MGW-local RTP Port (2000)\nConnect to MSC:5000"]; + mgw_bsc -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:2000)"]; + ...; + + bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:2000)"]; + m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"]; + m_sc -> mgw_msc [label="MGCP MDCX rtpbridge/1@mgw (MGW:2000)"]; + m_sc <- mgw_msc [label="MGCP MDCX rtpbridge/1@mgw OK"]; + ...; + + mgw_bsc <=> mgw_msc [label="RTP Audio MGW:2000 MSC:5000"]; + bts <=> mgw_bsc [label="Osmux Audio BTS:1985 MGW:1984, CID(uplink):5, CID(downlink):7"]; + ms <=> bts [label="Um Audio (bidirectional)"]; + ms <-> m_sc [label="DTAP CC ALERTING"]; +} diff --git a/common/chapters/osmux/mo_call_osmux_aoip.msc b/common/chapters/osmux/mo_call_osmux_aoip.msc index 9cb2e50..27e79ba 100644 --- a/common/chapters/osmux/mo_call_osmux_aoip.msc +++ b/common/chapters/osmux/mo_call_osmux_aoip.msc @@ -14,7 +14,7 @@ msc { # Allocate MGW/MSC Osmux endpoint m_sc -> mgw_msc [label="MGCP CRCX rtpbridge/*@mgw, X-Osmux: *"]; - mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"]; + mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, MGW's local CID 5"]; mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"]; bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP, extension IE: Osmux CID 5)"]; @@ -37,7 +37,7 @@ msc { ...; mgw_bsc <- bsc [label="MGCP CRCX rtpbridge/2@mgw (MSC:1984, X-Osmux: 5)"]; - mgw_bsc box mgw_bsc [label="Bind to MGW-local Osmux Port (1985)\nConnect to MSC:1984\nAllocate new recvCID 7"]; + mgw_bsc box mgw_bsc [label="Bind to MGW-local Osmux Port (1985)\nConnect to MSC:1984\nAllocate new MGW's local CID 7"]; mgw_bsc -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:1985, X-Osmux: 7)"]; ...; diff --git a/common/chapters/osmux/mo_call_osmux_sccplite.msc b/common/chapters/osmux/mo_call_osmux_sccplite.msc index 903da46..037805b 100644 --- a/common/chapters/osmux/mo_call_osmux_sccplite.msc +++ b/common/chapters/osmux/mo_call_osmux_sccplite.msc @@ -12,7 +12,7 @@ msc { # Allocate MGW/MSC Osmux endpoint m_sc -> mgw_msc [label="MGCP CRCX *@mgw, X-Osmux: *"]; - mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"]; + mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, MGW's local CID 5"]; mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"]; bsc <- m_sc [label="BSSAP ASSGN REQ (CIC:1)"]; @@ -39,7 +39,7 @@ msc { # MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding mgw_bsc <- m_sc [label="MGCP CRCX 1@mgw (MSC:1984, X-Osmux: 5)"]; - mgw_bsc box mgw_bsc [label="Bind to BTS-local Osmux Port (1985)\nAllocate new recvCID 7"]; + mgw_bsc box mgw_bsc [label="Bind to BTS-local Osmux Port (1985)\nAllocate new MGW's local CID 7"]; mgw_bsc -> m_sc [label="MGCP CRCX 1@mgw OK (MGW:1985, X-Osmux: 7)"]; mgw_bsc <- m_sc [label="MGCP MDCX 1@mgw (recvonly) "]; mgw_bsc box mgw_bsc [label="Connect Osmux socket to remote (MSC) Osmux Port"]; diff --git a/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc index 2aa8105..d309ebb 100644 --- a/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc +++ b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc @@ -18,7 +18,7 @@ msc { # NAT: MGW/MSC Osmux endpoint #bscnat -> bscnat [label="MGCP CRCX *@mgw, X-Osmux: *"]; - mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 2, recvCID 5"]; + mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 2, MGW's local CID 5"]; #mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"]; bsc <- bscnat [label="BSSAP ASSGN REQ (CIC:2)"]; @@ -48,7 +48,7 @@ msc { # MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding bscnat <- m_sc [label="MGCP CRCX 1@mgw (MSC:3000)"]; - bscnat box bscnat [label="Allocate new endpoint 2\nAllocate new recvCID 5\nBind to local Osmux Port (1984)\nBind to local RTP port 4000"]; + bscnat box bscnat [label="Allocate new endpoint 2\nAllocate new MGW's local CID 5\nBind to local Osmux Port (1984)\nBind to local RTP port 4000"]; mgw_bsc <- bscnat [label="MGCP CRCX 2@mgw (MSC:1984, X-Osmux: 5)"]; mgw_bsc -> bscnat [label="MGCP CRCX 2@mgw OK (MGW:1985, X-Osmux: 7)"]; bscnat -> m_sc [label="MGCP CRCX 1@mgw OK (MGW:4000)"]; diff --git a/common/chapters/osmux/network_osmux_abis.dot b/common/chapters/osmux/network_osmux_abis.dot new file mode 100644 index 0000000..578e0d1 --- /dev/null +++ b/common/chapters/osmux/network_osmux_abis.dot @@ -0,0 +1,32 @@ +digraph G { + rankdir = LR; + subgraph cluster_RAN { + OsmoBTS1 [label="OsmoBTS"]; + OsmoBTS2 [label="OsmoBTS"]; + OsmoBSC; + OsmoMGW [label="OsmoMGW\n(for BSC)"]; + + OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"]; + OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"]; + OsmoBSC -> OsmoMGW [label="MGCP", dir="both"]; + { rank = same; OsmoBSC; OsmoMGW } + + OsmoBTS1 -> OsmoMGW [label="Osmux", dir="both", color=red]; + OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"]; + + label = "RAN"; + } + subgraph cluster_CN { + OsmoMGW1 [label="OsmoMGW\n(for MSC)"]; + OsmoMSC [label="MSC\ne.g. OsmoMSC"]; + Core [label="Other CN Elements"]; + OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"]; + OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"]; + { rank = same; OsmoMSC; OsmoMGW1 } + OsmoMGW -> OsmoMGW1 [label="RTP", dir="both"]; + OsmoMGW1 -> Core [label="RTP", dir="both"]; + label = "CN"; + } + + OsmoBSC -> OsmoMSC [label="3GPP AoIP\nvia SIGTRAN/STP", dir="both"]; +} diff --git a/common/chapters/osmux/osmux.adoc b/common/chapters/osmux/osmux.adoc index 5e53b60..6862d9c 100644 --- a/common/chapters/osmux/osmux.adoc +++ b/common/chapters/osmux/osmux.adoc @@ -9,7 +9,7 @@ optimizations, eg. message batching and trunking, can result in significant cost reduction. Full reference document for the osmux protocol can be found here: -http://ftp.osmocom.org/docs/latest/osmux-reference.pdf +https://ftp.osmocom.org/docs/latest/osmux-reference.pdf In Osmocom satellite based GSM networks, the satellite link is envisioned to be in between the BSS and the core network, that is, between the BSC and the MSC @@ -18,6 +18,11 @@ multiplex payload audio streams from call legs between OsmoBSC and OsmoMSC (or OsmoBSCNAT). The MGW attached those components need of course also be aware of `Osmux` existence in order to properly set up the audio data plane. +Under some specific circumstances, the operator may decide to set up the network +with a bandwidth-limited (e.g. satellite) link between BTS and BSC. Hence, use of +the `Osmux` protocol is also possible between an Osmux capable BTS (like +OsmoBTS) and OsmoBSC (and its co-located MGW). + === Osmux and NAT It is quite usual for satellite based links to use NATs, which means any or both @@ -40,23 +45,41 @@ Osmux), discover the real public IP address and port of the peer (BSC/MGW). From that point on, the BSC/MGW punched a hole in the NAT (its connection table is updated) and MSC/MGW is able to send data back to it on that connection. -Moreover, NATs tend to drop connections from their connection tables after some -inactivity time, meaning a peer may receive notice about the other end not being -available while it actually is. This means the GSM network needs to be -configured in a way to ensure inactivity periods are short enough that this -cannot occur. That's the reason why OsmoMGW provides the `osmux dummy` VTY -command to enable sending dummy packets from time to time to keep the -connections alive. +In order to make use of the features above, OsmoMGW must be made aware +explicitly through VTY configuration that its peers are located behind a NAT. +This is done through the `osmux peer-behind-nat (on|off)` VTY commands. + +If OsmoMGW itself is behind a NAT, it must use the VTY config `rtp keep-alive` +(used for both RTP and Osmux) to at least the value `once`, in order for it to +punch the hole in its NAT so that its peer can know where to send packets back +to it. + +Another characteristic of NATs is that they tend to drop connections from their +connection tables after some inactivity time, meaning a peer may receive notice +about the other end not being available while it actually is. This means the GSM +network needs to be configured in a way to ensure inactivity periods are short +enough that this cannot occur. + +Hence, if OsmoMGW is behind a NAT, it is actually desirable to have the VTY +config `rtp keep-alive` configured with the `<1-120>` value in order to force +transmission of dummy packets ever few seconds. + +Osmux implementations such as OsmoMGW also come with the `osmux dummy` VTY +command to enable sending dummy AMR payloads to the peer even if no real data +was received (for instance if DTX is used). This is useful under some specific +satellite links which were proven to work unreliably if the total throughput in +use over the link changes over time. This way throughput resources are kept +pre-allocated until they are needed again (audio is received again). === CID allocation -Each peer (BSC/MGW and MSC/MGW) allocates its own _recvCID_, and receives from -the peer through the used GSM protocol the peer's _recvCID_, which becomes -the local _sendCID_ for that connection. +Each peer (BSC/MGW and MSC/MGW) allocates its own _local CID_, and receives from +its peer a _remote CID_ (aka the peer's _local CID_) through the used GSM +protocol. This _remote CID_ is then used to send Osmux frames to that peer. ---- -BSC/MGW(recvCID=Y,sendCID=?)<-X--MSC/MGW(recvCID=X,sendCID=?) -BSC/MGW(recvCID=Y,sendCID=X)--Y->MSC/MGW(recvCID=X,sendCID=Y) +BSC/MGW(localCID=Y,remoteCID=?)<-X--MSC/MGW(localCID=X,remoteCID=?) +BSC/MGW(localCID=Y,remoteCID=X)--Y->MSC/MGW(localCID=X,remoteCID=Y) ---- This way each peer is responsible for allocating and managing their own local @@ -75,13 +98,13 @@ localPort>` tuple, allowing for 256 Osmux CIDs per BSC and hence call legs per BSC. Each of the peers could actually have more than one Osmux socket towards the other peer, by using a pool of ports or IP addresses, so there's really not limit if required as long as there's a way to infer the initially negotiated -`<srcIP, srcPort, dstIP, dstPort, sendCID>` tuple from the received audio +`<srcIP, srcPort, dstIP, dstPort, remoteCID>` tuple from the received audio packets. However, due to some constrains from in between NATs explained in section above, BSC/MGW IP address and port are not a priory known, and could change between different connections coming from it. As a result, it is difficult to infer the -entire tuple, so for now MGW needs to allocate its Osmux _recvCID_ in a clever +entire tuple, so for now MGW needs to allocate its Osmux _local CID_ in a clever way, in order to be able to identify the full tuple from it. Hence, currently OsmoMGW CID allocation implementation shares CID between all @@ -139,3 +162,18 @@ include::mo_call_osmux_sccplite_nat.msc[] ---- include::mgcp_extension_osmux.adoc[] + +=== Abis setup with Osmux + +[[fig-network-osmux-aoip]] +.Sample node diagram of Osmux enabled in the Abis interface +[graphviz] +---- +include::network_osmux_abis.dot[] +---- + +.MO-call with Osmux enabled on Abis +[mscgen] +---- +include::mo_call_osmux_abis.msc[] +---- diff --git a/common/chapters/port_numbers.adoc b/common/chapters/port_numbers.adoc index 477c3b3..16b9ce3 100644 --- a/common/chapters/port_numbers.adoc +++ b/common/chapters/port_numbers.adoc @@ -10,6 +10,7 @@ which protocol / interface. [options="header",cols="10%,10%,40%,40%"] |=============== |L4 Protocol|Port Number|Purpose|Software +|UDP|1984|Osmux|osmo-mgw, osmo-bts |UDP|2427|MGCP GW|osmo-bsc_mgcp, osmo-mgw |TCP|2775|SMPP (SMS interface for external programs)|osmo-nitb |TCP|3002|A-bis/IP OML|osmo-bts, osmo-bsc, osmo-nitb @@ -50,11 +51,19 @@ which protocol / interface. |TCP|4268|telnet (VTY)|osmo-uecups |SCTP|4268|UECUPS|osmo-uecups |TCP|4269|telnet (VTY)|osmo-e1d +|TCP|4270|telnet (VTY)|osmo-isdntap |TCP|4271|telnet (VTY)|osmo-smlc |TCP|4272|Control Interface|osmo-smlc +|TCP|4273|telnet (VTY)|osmo-hnodeb +|TCP|4274|Control Interface|osmo-hnodeb +|TCP|4275|telnet (VTY)|osmo-upf +|TCP|4276|Control Interface|osmo-upf +|TCP|4277|telnet (VTY)|osmo-pfcp-tool +|TCP|4278|Control Interface|osmo-pfcp-tool |UDP|4729|GSMTAP|Almost every osmocom project |TCP|5000|A/IP|osmo-bsc, osmo-bsc_nat |UDP|23000|GPRS-NS over IP default port|osmo-pcu, osmo-sgsn, osmo-gbproxy +|TCP|48049|BSC-CBC (CBSP) default port|osmo-bsc, osmo-cbc |=============== //// ATTENTION: Keep this list in sync with all of: diff --git a/common/chapters/preface.adoc b/common/chapters/preface.adoc index 76e6f48..f102aea 100644 --- a/common/chapters/preface.adoc +++ b/common/chapters/preface.adoc @@ -1,7 +1,7 @@ == Foreword Digital cellular networks based on the GSM specification were designed -in the late 1980ies and first deployed in the early 1990ies in Europe. +in the late 1980s and first deployed in the early 1990s in Europe. Over the last 25 years, hundreds of networks were established globally and billions of subscribers have joined the associated networks. @@ -79,6 +79,10 @@ following key individuals and organizations, in no particular order: * Jan Luebbe, Stefan Schmidt, Daniel Willmann, Pablo Neira, Nico Golde, Kevin Redon, Ingo Albrecht, Alexander Huemer, Alexander Chemeris, Max Suraev, Tobias Engel, Jacob Erlbeck, Ivan Kluchnikov +* NLnet Foundation, for providing funding for a number of individual work items + within the Osmocom universe, such as LTE support in OsmoCBC or GPRS/EGPRS + support for Ericsson RBS6000. +* WaveMobile Ltd, for many years of sponsoring. May the source be with you! @@ -117,13 +121,13 @@ operator'', but it is about a collaborative, open development model. It is about sharing ideas and code, but also about sharing the effort of software development and maintenance. -If your organization is benefitting from using Osmocom software, please +If your organization is benefiting from using Osmocom software, please consider ways how you can contribute back to that community. Such contributions can be many-fold, for example * sharing your experience about using the software on the public mailing lists, helping to establish best practises in using/operating it, -* providing qualified bug reports, work-arounds +* providing qualified bug reports, workarounds * sharing any modifications to the software you may have made, whether bug fixes or new features, even experimental ones * providing review of patches @@ -289,10 +293,15 @@ may have. If you don't have a support package / contract, you have the option of using the resources put together by the Osmocom community -at http://projects.osmocom.org/, checking out the wiki and +at https://projects.osmocom.org/, checking out the wiki and the mailing-list for community-based assistance. Please always remember, though: The community has no obligation to help you, and you should address your requests politely to them. The information (and software) provided at osmocom.org is put together by volunteers for free. Treat them like a friend whom you're asking for help, not like a supplier from whom you have bought a service. + +If you would like to obtain professional/commercial support on Osmocom +CNI, you can always reach out to sales@sysmocom.de to discuss your +support needs. Purchasing support from sysmocom helps to cover the +ongoing maintenance of the Osmocom CNI software stack. diff --git a/common/chapters/qos-dscp-pcp.adoc b/common/chapters/qos-dscp-pcp.adoc index 3f97941..81a9e4e 100644 --- a/common/chapters/qos-dscp-pcp.adoc +++ b/common/chapters/qos-dscp-pcp.adoc @@ -77,7 +77,7 @@ the so-called PCP (Priority Code Point) field in the IEEE 802.1q (VLAN) header. NOTE:: This means that PCP functionality requires the use of IEEE 802.q -VLAN. You cannot use PCP without VLAN +VLAN. You cannot use PCP without VLAN. The Linux kernel assigns IEEE 802.1q PCP bits based on a _mapping_ between the _priority_ and the PCP value. Each VLAN network device @@ -148,7 +148,7 @@ follows: . configure the osmocom program to set the DSCP value . use the default DSCP -> priority mapping, if possible -. configure an egrees QoS map to map from priority to PCP +. configure an egress QoS map to map from priority to PCP If the desired combination of DSCP + PCP cannot be achieved that way, due to the rather static default kernel mapping table, one needs to go @@ -156,6 +156,6 @@ one step further: . configure the osmocom program to set the DSCP value . use packet filter rules to set the priority based on DSCP -. configure an egrees QoS map to map from priority to PCP +. configure an egress QoS map to map from priority to PCP include::{srcdir}/chapters/qos-example.adoc[] diff --git a/common/chapters/sigtran-osmocom.adoc b/common/chapters/sigtran-osmocom.adoc index 3fbaac2..ddba669 100644 --- a/common/chapters/sigtran-osmocom.adoc +++ b/common/chapters/sigtran-osmocom.adoc @@ -38,7 +38,7 @@ Protocol. ==== The present (2017) In 2017, sysmocom was tasked with implementing a 3GPP AoIP compliant A -interface. This meant that lot of things had to change in the +interface. This meant that a lot of things had to change in the existing code: * removal of the existing hard-wired SCCPlite/IPA code from OsmoBSC @@ -50,7 +50,7 @@ existing code: BSSAP * introduction of an A interface in OsmoMSC (which so far offered Iu only) -* port of the existing SUA-baesd IuCS and IuPS over to the SCCP User +* port of the existing SUA-based IuCS and IuPS over to the SCCP User SAP of libosmo-sigtran. * Implementation of ETSI M3UA as preferred/primary transport layer for SCCP @@ -112,7 +112,7 @@ the corresponding xUA Server (<<xua-server>>) must be configured with `accept-asp-connections dynamic-permitted`. To enable dynamic registration of routing keys via RKM, the -corresponding SS7 Instance (<<ss7-instance>>) must be confgured with +corresponding SS7 Instance (<<ss7-instance>>) must be configured with `xua rkm routing-key-allocation dynamic-permitted`. This is of course highly insecure and can only be used in trusted, @@ -345,11 +345,11 @@ An AS has the following properties: |Description|More verbose description (for human user only) |Protocol|Protocol (M3UA, SUA, IPA) to be operated by this server |Routing Key|Routing Key (mostly Point Code) routed to this AS -|Traffic Mode|Theoretically Broadcast, Load-Balance. Currently only Override +|Traffic Mode|Broadcast, Loadshare or Override |Recovery Timeout|Duration of the AS T(r) recovery timer. During this time, outgoing messages are queued. If the AS is ACTIVE before timer expiration, the queue is drained. At - expriation, the queue is flushed. + expiration, the queue is flushed. |State|Application Server State (Down, Inactive, Active, Pending) |ASPs|Which ASPs are permitted to transfer traffic for this AS |==== @@ -360,7 +360,7 @@ An Application Server Process corresponds to a given SCTP (or TCP) connection. From the STP/SG (Server) point-of-view, those are incoming connections from Application Servers such as the BSCs. From the ASP (Client) Point of view, it has one `osmo_ss7_asp` object for -each outbound SIGTARN connection. +each outbound SIGTRAN connection. An ASP has the following properties: diff --git a/common/chapters/sigtran.adoc b/common/chapters/sigtran.adoc index cbf513e..75767e3 100644 --- a/common/chapters/sigtran.adoc +++ b/common/chapters/sigtran.adoc @@ -33,7 +33,7 @@ On top of the Physical Layer is the Message Transfer Part (MTP). === Message Transfer Part (MTP) MTP is the lower layer of the SS7 protocol stack. It is comprised of -two sub-layes, called MTP2 and MTP3. +two sub-layers, called MTP2 and MTP3. Nodes in a MTP network are addressed by their unique PC (Point Code). @@ -54,7 +54,7 @@ Linkset exist both for load sharing as well as for fail over purposes. ==== Point Codes The length of point codes depends on the particular MTP dialect that -is used. In the 1980ies, when international telephony signaling +is used. In the 1980s, when international telephony signaling networks were established, most countries had their own national dialects with certain specifics. @@ -210,7 +210,7 @@ to the network, such as HLR or MSC) were attached to the existing old SS7 backbone by means as SUA and M3UA. Over time, even the links of the actual network backbone networks became more and more IP based. -In order to replace existing TDM-based SS7 links/liksets with SIGTRAN, +In order to replace existing TDM-based SS7 links/linksets with SIGTRAN, the M2UA or M2PA variants are used as a kind of drop-in replacement for physical links. @@ -254,8 +254,8 @@ interfaced with the SS7 network by means of one of the SIGTRAN protocols. An Application Server can have one or more Application Server Processes -associated with it. This functionality (currently not implemented in -Osmocom) can be used for load-balancing or fail-over scenarios. +associated with it. This functionality can be used for load-balancing or +fail-over scenarios. ===== Application Server Process (ASP) @@ -334,7 +334,7 @@ stackings) operates on top of both IPv4 and IPv6. As the entire underlying IP transport is transparent to the SS7/SCCP applications, there is no restriction on whether to use SIGTRAN over IPv4 or IPv6. -==== SCTP multi-homing in SIGTARN +==== SCTP multi-homing in SIGTRAN SCTP, unlike more traditional IP L4 protocols (TCP, UDP) doesn't work based on a _connection_ between source IP:port and Destination IP:port. @@ -358,6 +358,133 @@ associations it manages. The user can achieve this by specifying multiple `local-ip` VTY commands within one `asp` (SCTP client role) or within one `listen m3ua 2905` (SCTP server role). +==== SCTP Primary Address + +SCTP has the concept of "primary address" in an association. The primary address +is a remote address selected from those announced by the peer, and it is the +"active" one chosen to transmit user data. The other remote addresses, that are +not used, are kept as backups. They are in general only used to transmit user +data whenever the SCTP implementation decides to change the primary address, be +it due to user policy configuration change or due to the previous primary link +becoming unusable. Only confirmed remote addresses (through HEARTBEAT mechanism) +are electable to be used as primary address. + +By default, the Linux kernel SCTP stack implementation will probably take the +first remote address provided at connect() time in order to start the initial +handshake, and continue with next provided remote addresses if the first one +fails to confirm the handshake. The remote address which successfully confirmed +the handshake is then used as a primary address (since it's likely the only +confirmed so far), and will be kept until the link is considered down. + +Some deployment setups may have requirements on preferred links to be used when +transmitting data (eg. network setups with primary and secondary paths). This +can be accomplished by explicitly notifying the kernel to use one of the remote +addresses through the SCTP_PRIMARY_ADDR sockopt, plus monitoring the address +availability changes on the socket and re-enforcing the primary address when it +becomes available again. This is supported in the Osmocom SIGTRAN stack by using +the `primary` parameter in one of the `remote-ip` commands under the `asp` node: + +---- +cs7 instance 0 + asp my-asp 2905 0 m3ua + remote-ip 10.11.12.13 + remote-ip 16.17.18.19 primary <1> + ... +---- +<1> Use 16.17.18.19 as primary address for the SCTP association. User data will +be in general transmitted over this path. + +==== SCTP Peer Primary Address + +The SCTP extension ASCONF (RFC5061) allows, when negotiated and supported by +both peers, to dynamically announce to the peer the addition or deletion of IP +addresses to the association. It also allows one peer announcing to the other +peer the desired IP address it should be using as a primary address when sending +data to it. + +In the Linux kernel SCTP stack, this is accomplished by setting the sockopt +SCTP_SET_PEER_PRIMARY_ADDR, which will trigger an ASCONF SCTP message to the +peer with the provided local IP address. This is supported in the Osmocom +SIGTRAN stack by using the `primary` parameter in one of the `local-ip` commands +under the `asp` node: + +---- +cs7 instance 0 + asp my-asp 2905 0 m3ua + local-ip 10.11.12.13 + local-ip 16.17.18.19 primary <1> + ... +---- +<1> Announce 16.17.18.19 to the peer as the primary address to be used when +transmitting user data to us. + +In order to be able to use this feature, the SCTP association peer must support +the ASCONF extension. The extension support is negotiation during the INIT +handshake of the association. Furthermore, for ASCONF features to work properly, +the assoc also needs to announce/use the AUTH extension, as per RFC5061 section +4.2.7. Otherwise, the peer receiving an SCTP INIT with +`ExtensionFeatures=ASCONF,ASCONF_ACK`` but without AUTH, will reject the +association with an ABORT since it's not complying with specifications (this +behavior can be tweaked through sysctl "net.sctp.addip_noauth_enable"). + +As of the time of writing this documentation (linux 6.4.12) and since basically +ever, those extensions are runtime-disabled by default. They can be enabled per +socket using the kernel sockopts SCTP_ASCONF_SUPPORTED and SCTP_AUTH_SUPPORTED, +and that's what the Osmocom stack is currently doing for all SCTP sockets. +However, those sockopts are farily new (linux v5.4), which means user running +older kernels will see in the logs setting those sockopts fail, but connection +will keep ongoing, simply without those features available (so setting `primary` +in the configuration won't have any effect here). +On those older kernels, if this feature is still desired, it can be used +by means of enabling the SCTP extensions in all socket system-wide through sysctl: +---- +net.sctp.auth_enable=1 +net.sctp.addip_enable=1 +---- + +==== SCTP INIT Parameters + +Several SCTP INIT parameters can be configured through VTY, which will be passed +to the Linux Kernel SCTP stack and used whenever an association is being +established. + +On the client side (see <<sctp_role>>), the parameters are configured in the `asp` node: +---- +cs7 instance 0 + asp my-asp 2905 0 m3ua + sctp-role client + sctp-param init num-ostreams 250 <1> + sctp-param init max-instreams 300 <2> + sctp-param init max-attempts 3 <3> + sctp-param init timeout 10000 <4> + ... +---- +<1> The number of streams from the server to the client. This value is +transmitted during SCTP INIT ACK packet. +<2> Announce to the server that a maximum of up to 300 inbound SCTP streams are +supported. This value is transmitted during SCTP INIT packet. +<3> Initial SCTP handshake will be attempted 3 times before considering the +connection failed. +<4> Retransmit an SCTP INIT message after 10000 ms if no answer is received. + +On the server side (see <<sctp_role>>), the parameters are configured in the `listen` node: +---- +cs7 instance 0 + asp my-asp 2905 0 m3ua + sctp-role server + listen m3ua 2905 + sctp-param init num-ostreams 250 <1> + sctp-param init max-instreams 300 <2> + ... +---- +<1> Announce to the server that up to 250 outbound SCTP streams (server to +client) may be requested. This value is transmitted during SCTP INIT packet, and +should be equal or lower to the `max-instreams` value received from the client +during SCTP INIT packet. +<2> Announce to the server that a maximum of up to 300 inbound SCTP streams are +supported. This value is transmitted during SCTP INIT ACK packet. + +[[sctp_role]] ==== SCTP role The _SCTP role_ defines which of the two L4 protocol roles SCTP assumes: @@ -380,7 +507,7 @@ M3UA connection implements. 3GPP specifies the following role: Osmocom (libosmo-sigtran) implements both the SGP and ASP roles, but not the IPSP role. -==== traffic modes in SIGTRAN +==== Traffic Modes in SIGTRAN Whenever an AS consists of multiple ASPs, the traffic mode expresses how messages are distributed between those ASPs. diff --git a/common/chapters/spectrum.adoc b/common/chapters/spectrum.adoc index 25e474e..5a6286f 100644 --- a/common/chapters/spectrum.adoc +++ b/common/chapters/spectrum.adoc @@ -14,8 +14,8 @@ communications networks, which not only may cause civil claims by the operator of the interfered network, but is punishable as a crime under most jurisdictions. -sysmocom disclaims any responsibility for illegal / unlicensed use of -its products. +sysmocom and/or the authors of the Osmocom software disclaim any +responsibility for illegal / unlicensed use of its products. === Regulatory authorities by country diff --git a/common/chapters/trx_if.adoc b/common/chapters/trx_if.adoc index 9638133..a7be07c 100644 --- a/common/chapters/trx_if.adoc +++ b/common/chapters/trx_if.adoc @@ -569,15 +569,15 @@ is used in EDGE). .MTS field structure ---- -+-----------------+---------------------------------------+ -| 7 6 5 4 3 2 1 0 | bit numbers (value range) | -+-----------------+---------------------------------------+ -| X . . . . . . . | NOPE / IDLE frame indication (0 or 1) | -+-----------------+---------------------------------------+ -| . X X X X . . . | Modulation, TS set number (see below) | -+-----------------+---------------------------------------+ -| . . . . . X X X | Training Sequence Code (0..7) | -+-----------------+---------------------------------------+ ++-----------------+----------------------------------------+ +| 7 6 5 4 3 2 1 0 | bit numbers (value range) | ++-----------------+----------------------------------------+ +| X . . . . . . . | NOPE / IDLE frame indication (0 or 1) | ++-----------------+----------------------------------------+ +| . X X X X . . . | Modulation, TS set number (see below) | ++-----------------+----------------------------------------+ +| . . . . . X X X | Training / Synch. Sequence Code (0..7) | ++-----------------+----------------------------------------+ ---- NOPE / IDLE frame indication (referred to as NOPE.ind):: @@ -618,11 +618,11 @@ The one exception is a special radio block occasionally used on the Uplink consisting of a sequence of four Access Bursts (see 3GPP TS 44.060). The transceiver shall use `0110` as the modulation type to indicate that. -Training Sequence Code:: -The Training Sequence Code identifies the Training Sequence of a received -burst. The value of this field corresponds to one of the sequences defined -in 3GPP TS 45.002, section 5.2, and depends on the actual modulation and -the TSC set indicated by the preceding bits. +Training / Synch. Sequence Code:: +In combination with a modulation type and a TS set number, this field uniquely +identifies the Training Sequence of a received Normal Burst (see tables 5.2.3a-d) +or Synchronization Burst (see table 5.2.5-3), or the Synch. Sequence of a +received Access Burst (see table 5.2.7-3 and 5.2.7-4). ==== Downlink Data Burst diff --git a/common/snippets/systemd.adoc b/common/snippets/systemd.adoc new file mode 100644 index 0000000..671dab1 --- /dev/null +++ b/common/snippets/systemd.adoc @@ -0,0 +1,70 @@ +=== Running as a systemd service + +Most modern GNU/Linux distributions use `systemd` to manage processes. +We provide an example systemd service unit file in the +`contrib/systemd/` sub-directory of the source code. + +Please see your distribution documentation and/or the generic systemd +user manuals for more in-depth information. + +The included systemd service unit file assumes your configuration file +is stored in `/etc/osmocom/`, but feel free to adjust this according to +your local environment. + +This service unit file is also what is used (and installed) by the +official dpkg and rpm packages published by Osmocom. For more +information, see +https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages + +On a system utilizing this systemd service unit, you can use the +following standard commands: + +==== Starting a service + +.Example shell command to start the osmo-bsc service +---- +# systemctl start osmo-bsc +---- +==== Stopping a service + +.Example shell command to stop the osmo-bsc service +---- +# systemctl stop osmo-bsc +---- + +==== Enabling a service for automatic start on boot + +.Example shell command to enable the osmo-bsc service +---- +# systemctl enable osmo-bsc +---- + +NOTE: This will only affect service starting at the next system +boot; it will not start the service if it is not running right now. + +==== Disabling a service from automatic start on boot + +.Example shell command to disable the osmo-bsc service +---- +# systemctl disable osmo-bsc +---- + + +==== Checking current status of a service + +.Example shell command to check the status of osmo-e1d +---- +# systemctl status osmo-e1d +● osmo-e1d.service - Osmocom E1 Interface Daemon + Loaded: loaded (/etc/systemd/system/osmo-e1d.service; enabled; vendor preset: enabled) + Active: active (running) since Tue 2022-11-01 13:12:54 CET; 4 days ago + Main PID: 629 (osmo-e1d) + Tasks: 2 (limit: 4673) + Memory: 2.0M + CPU: 6min 8.464s + CGroup: /system.slice/osmo-e1d.service + └─629 /usr/local/bin/osmo-e1d -c /etc/osmocom/osmo-e1d.cfg + +Nov 03 19:22:56 divo osmo-e1d[629]: Thu Nov 3 19:22:56 2022 DE1D usb.c:734 (I0) GPS antenna status ch> +Nov 03 19:23:00 divo osmo-e1d[629]: Thu Nov 3 19:23:00 2022 DE1D usb.c:734 (I0) GPS antenna status +---- diff --git a/debian/changelog b/debian/changelog index f19b6d4..bcd956b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,129 @@ +osmo-gsm-manuals-dev (1.5.0) unstable; urgency=medium + + [ Max ] + * SIGTRAN: fix typo + + [ Oliver Smith ] + * editorconfig: new file + * Change upload path to project/master/ + * build/Makefile.common.inc: unset OSMO_REPOSITORY + * build/{diag,mscgen}-filter.conf: png -> svg + * build/graphviz-filter.conf: add config for svgs + * Cosmetic: build/Makefile.common.inc: add comments + * build/Makefile.common: move clean/distclean down + * build/Makefile.common: shrink pdfs before publish + * build/Makefile.common: full path for shrink script + * debian: set compat level to 10 + * VTY references: set git version and date + * build/Makefile.docbook: fix INC_DIR for openbsc + * build/Makefile.asciidoc: print less clutter + * build: replace inkscape with rsvg-convert + + [ Vilius Panevėžys ] + * Fix mistypes + + [ Harald Welte ] + * chapters/*: Fix typos + * chapters/mncc: Update the wording to be less confusing and more up-to-date + * chapters/cell-broadcast: Bring up-to-date with reality + * chapters/logging: Expand documentation on GSMTAP logging + * chapters/preface: Thank NLnet and WaveMobile + * common/chapters: http -> https + * preface: indicate where to ask for commercial support + * chapters/spectrum: Extend disclaimer to Osmocom authors + + [ Pau Espin Pedrol ] + * sigtran: Update supported xUA Traffic modes + * Write explicit role & sctp-role fields in ASP configurations + * mgwpool: Document keepalive feature + * sigtran: Document SCTP (peer) primary address configuration + + -- Pau Espin Pedrol <pespin@sysmocom.de> Tue, 12 Sep 2023 12:24:03 +0200 + +osmo-gsm-manuals-dev (1.4.0) unstable; urgency=medium + + [ Pau Espin Pedrol ] + * port_number.adoc: Add default osmux port + * osmux: Use local/remote CID terminology + * Document osmux use in Abis interface + * osmux: Improve NAT related documentation + * Copy mgwpool.adoc from osmo-bsc.git + * mgwpool.adoc: Fix typo + * mgwpool.adoc: Use {program-name} instead of BSC + + [ Vadim Yanitskiy ] + * TRXD: further clarify meaning of Training / Synch. Sequence Code + + [ Harald Welte ] + * port_numbers.adoc: Allocate VTY port number for osmo-isdntap + * add a documentation snippet for systemd services + * doc: Add a general chapter on installation of the Osmocom software + * gfdl.adoc: Fix cross-reference typo + * merge gb-ns2 "chapters" in one + + [ Max ] + * rate counter: add StatsD note + + -- Pau Espin Pedrol <pespin@sysmocom.de> Tue, 07 Feb 2023 11:43:11 +0100 + +osmo-gsm-manuals-dev (1.3.0) unstable; urgency=medium + + [ Philipp Maier ] + * counters-overview: add documentation about socket statistics + + [ Alexander Couzens ] + * common: gb-ns2: remove empty VTY chapter + * common: gb-ns2: update ip-sns configuration example + * common: gb-ns2: correct ip.access static configuration + * common: gb-ns2: fix typo in configures + * common: gb-ns2: add chapter Gb/NS maintenance + + [ Harald Welte ] + * Add CBSP port number to default list of ports + * bibliography: Add reference to TS 48.049 (CBSP) + * glossary: add CBSP, CBC, CBS + * port_numbers: Add missing records for osmo-upf, pfcp-tool, hnodeb + + [ Pau Espin Pedrol ] + * sigtran: Remove old comment about non-implemented stuff + * sigtran: Use caps in section header + + -- Pau Espin Pedrol <pespin@sysmocom.de> Tue, 28 Jun 2022 17:27:15 +0200 + +osmo-gsm-manuals-dev (1.2.0) unstable; urgency=medium + + [ Harald Welte ] + * add README.md to describe what this repo is about + * build: Switch from rita -> ftp.osmocom.org + * bibliography: Re-introduce RFC768 (UDP) + * Add new common chapter about QoS, IP DSCP and IEEE 802.1q PCP + * glossary: fix various typos I introduced. + + [ Vadim Yanitskiy ] + * fix tests/Makefile.am: exclude file 'mgcp_extension_osmux.adoc' + * fix missing and/or non-existent linked references + * TRXD: clarify modulation specific length of Soft-/Hard-bits + * TRXD: rework description of the NOPE / IDLE frame indication + * TRXD: generalize description of the 'RFU' ('PAD') field + * TRXD: add documentation for TRXDv2 protocol + * TRXDv2: add primary/shadow classification for VAMOS PDUs + * mncc: do not mention deprecated -m / --mncc-sock options + + [ Alexander Couzens ] + * common/chapters: extend gb/ns2 chapters + + [ Neels Hofmeyr ] + * bib: add reference to 3GPP TS 45.002, for Training Sequence definitions + + [ Oliver Smith ] + * port_numbers: add osmo-pcap-client, -server + * d/patches/build-for-debian8.patch: remove + + [ Pau Espin Pedrol ] + * cs7-config.adoc: Improve doc on default SS7 SCTP addresses + + -- Pau Espin Pedrol <pespin@sysmocom.de> Tue, 16 Nov 2021 13:18:04 +0100 + osmo-gsm-manuals-dev (1.1.0) unstable; urgency=medium [ Harald Welte ] diff --git a/debian/compat b/debian/compat index ec63514..f599e28 100644 --- a/debian/compat +++ b/debian/compat @@ -1 +1 @@ -9 +10 diff --git a/debian/control b/debian/control index bf46840..908ca99 100644 --- a/debian/control +++ b/debian/control @@ -1,10 +1,10 @@ Source: osmo-gsm-manuals-dev Section: devel Priority: optional -Maintainer: Oliver Smith <osmith@sysmocom.de> +Maintainer: Osmocom team <openbsc@lists.osmocom.org> Build-Depends: autotools-dev, dh-autoreconf, - debhelper (>= 9), + debhelper (>= 10), pkg-config, # All below also need to be in Depends asciidoc, @@ -12,7 +12,7 @@ Build-Depends: autotools-dev, dblatex, docbook5-xml, graphviz, - inkscape, + librsvg2-bin, libxml2-utils, mscgen, python3-nwdiag, @@ -28,7 +28,7 @@ Depends: ${misc:Depends}, dblatex, docbook5-xml, graphviz, - inkscape, + librsvg2-bin, libxml2-utils, mscgen, python3-nwdiag, diff --git a/tests/Makefile.am b/tests/Makefile.am index 784f61f..0761d48 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -34,6 +34,7 @@ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc VTY_REFERENCE = test-vty-reference.xml test2-vty-reference.xml include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc +OSMO_REPOSITORY = osmo-gsm-manuals include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc |