diff options
58 files changed, 3281 insertions, 379 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/README.md b/README.md new file mode 100644 index 0000000..a3b951b --- /dev/null +++ b/README.md @@ -0,0 +1,10 @@ +osmo-gsm-manuals +================ + +This repository contains build infrastructure as well as common +chapters for the Osmocom CNI (Cellular Network Infrastructure) +manuals. + +PDF renderings of the resulting manuals are published at + + https://ftp.osmocom.org/docs/latest/ 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 b98e83f..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,18 +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: all - mkdir -p out - cp *.pdf out - rsync -avz -e "$(SSH_COMMAND)" ./out/ docs@rita.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: @@ -39,6 +51,7 @@ publish: all # - 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; \ @@ -46,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 373db7d..6eb48d0 100644 --- a/build/Makefile.docbook.inc +++ b/build/Makefile.docbook.inc @@ -12,7 +12,7 @@ # # OSMO_GSM_MANUALS_DIR = .. # DOCBOOKS = osmo_yada.xml osmo_moo.xml -# ASCIIDOC_DEPS = $(srcdir)/for_all/*.xml +# DOCBOOKS_DEPS = $(srcdir)/for_all/*.xml # include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.docbook.inc # osmo_yada.pdf: yada/*.xml # @@ -27,13 +27,34 @@ UPLOAD_FILES += $(DOCBOOKS_PDF) all: $(DOCBOOKS_PDF) +# Allow the users to re-define the include directory +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:$$PWD/generated" \ - $(dblatex_quiet) -P draft.mode=no -o $(notdir $@) $< - + 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/Makefile.vty-reference.inc b/build/Makefile.vty-reference.inc index c1db67b..878c841 100644 --- a/build/Makefile.vty-reference.inc +++ b/build/Makefile.vty-reference.inc @@ -49,49 +49,54 @@ DOCBOOKS = $(VTY_REFERENCE) +# Directory for intermediate results +GEN_DIR = generated + # First VTY reference -DOCBOOKS_DEPS = generated/docbook_vty.xml +DOCBOOKS_DEPS = $(GEN_DIR)/docbook_vty.xml -# Additional VTY references: prepend "generated/docbook_" +# Additional VTY references: prepend "$(GEN_DIR)/docbook_" # For example: # VTY_REFERENCE = osmosgsn-vty-reference.xml osmogbproxy-vty-reference.xml -# DOCBOOK_DEPS = generated/docbook_vty.xml generated/docbook_osmogbproxy-vty-reference.xml -DOCBOOKS_DEPS += $(patsubst %,generated/docbook_%,$(filter-out $(firstword $(VTY_REFERENCE)),$(VTY_REFERENCE))) +# DOCBOOK_DEPS = $(GEN_DIR)/docbook_vty.xml $(GEN_DIR)/docbook_osmogbproxy-vty-reference.xml +DOCBOOKS_DEPS += $(patsubst %,$(GEN_DIR)/docbook_%,$(filter-out $(firstword $(VTY_REFERENCE)),$(VTY_REFERENCE))) include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.docbook.inc MERGE_DOC = $(shell realpath $(OSMO_GSM_MANUALS_DIR)/merge_doc.xsl) -CLEAN_FILES += generated +CLEAN_FILES += $(GEN_DIR) CLEAN_FILES += $(BUILT_REFERENCE_XML) # First VTY reference -generated/docbook_vty.xml: \ +$(GEN_DIR)/docbook_vty.xml: \ $(srcdir)/vty/*xml \ $(BUILT_REFERENCE_XML) \ $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \ $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl + mkdir -p $(GEN_DIR) $(OSMO_GSM_MANUALS_DIR)/build/vty_reference_combine.sh "$(MERGE_DOC)" \ $$($(OSMO_GSM_MANUALS_DIR)/build/find_existing_path.sh "vty/*reference.xml" $(builddir) $(srcdir)) \ $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ - $(srcdir)/vty/*additions*.xml - xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl generated/combined.xml \ - > generated/docbook_vty.xml + $(srcdir)/vty/*additions*.xml > $(GEN_DIR)/combined.xml + xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl $(GEN_DIR)/combined.xml \ + > $(GEN_DIR)/docbook_vty.xml # Additional VTY references -generated/docbook_%-vty-reference.xml: \ +$(GEN_DIR)/docbook_%-vty-reference.xml: \ $(srcdir)/vty-%/*xml \ $(BUILT_REFERENCE_XML) \ $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \ $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl - export VTYDIR_NAME="vty-$(patsubst generated/docbook_%-vty-reference.xml,%,$@)" && \ + export VTYDIR_NAME="vty-$(patsubst $(GEN_DIR)/docbook_%-vty-reference.xml,%,$@)" && \ export VTYDIR_SRC="$(srcdir)/$$VTYDIR_NAME" && \ export VTYDIR_BUILD="$(builddir)/$$VTYDIR_NAME" && \ export VTYGEN="$@_combine" && \ + mkdir -p $$VTYGEN && \ $(OSMO_GSM_MANUALS_DIR)/build/vty_reference_combine.sh "$(MERGE_DOC)" \ $$($(OSMO_GSM_MANUALS_DIR)/build/find_existing_path.sh "*reference.xml" $$VTYDIR_BUILD $$VTYDIR_SRC) \ $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ - $$VTYDIR_SRC/*additions*.xml && \ + $$VTYDIR_SRC/*additions*.xml > $$VTYGEN/combined.xml && \ xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl $$VTYGEN/combined.xml > "$@" 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/known_hosts b/build/known_hosts index c78b03d..de29e93 100644 --- a/build/known_hosts +++ b/build/known_hosts @@ -1,3 +1,3 @@ -[rita.osmocom.org]:48 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDgQ9HntlpWNmh953a2Gc8NysKE4orOatVT1wQkyzhARnfYUerRuwyNr1GqMyBKdSI9amYVBXJIOUFcpV81niA7zQRUs66bpIMkE9/rHxBd81SkorEPOIS84W4vm3SZtuNqa+fADcqe88Hcb0ZdTzjKILuwi19gzrQyME2knHY71EOETe9Yow5RD2hTIpB5ecNxI0LUKDq+Ii8HfBvndPBIr0BWYDugckQ3Bocf+yn/tn2/GZieFEyFpBGF/MnLbAAfUKIdeyFRX7ufaiWWz5yKAfEhtziqdAGZaXNaLG6gkpy3EixOAy6ZXuTAk3b3Y0FUmDjhOHllbPmTOcKMry9 -[rita.osmocom.org]:48 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPdWn1kEousXuKsZ+qJEZTt/NSeASxCrUfNDW3LWtH+d8Ust7ZuKp/vuyG+5pe5pwpPOgFu7TjN+0lVjYJVXH54= -[rita.osmocom.org]:48 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK8iivY70EiR5NiGChV39gRLjNpC8lvu1ZdHtdMw2zuX +[ftp.osmocom.org]:48 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDgQ9HntlpWNmh953a2Gc8NysKE4orOatVT1wQkyzhARnfYUerRuwyNr1GqMyBKdSI9amYVBXJIOUFcpV81niA7zQRUs66bpIMkE9/rHxBd81SkorEPOIS84W4vm3SZtuNqa+fADcqe88Hcb0ZdTzjKILuwi19gzrQyME2knHY71EOETe9Yow5RD2hTIpB5ecNxI0LUKDq+Ii8HfBvndPBIr0BWYDugckQ3Bocf+yn/tn2/GZieFEyFpBGF/MnLbAAfUKIdeyFRX7ufaiWWz5yKAfEhtziqdAGZaXNaLG6gkpy3EixOAy6ZXuTAk3b3Y0FUmDjhOHllbPmTOcKMry9 +[ftp.osmocom.org]:48 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPdWn1kEousXuKsZ+qJEZTt/NSeASxCrUfNDW3LWtH+d8Ust7ZuKp/vuyG+5pe5pwpPOgFu7TjN+0lVjYJVXH54= +[ftp.osmocom.org]:48 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK8iivY70EiR5NiGChV39gRLjNpC8lvu1ZdHtdMw2zuX 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/build/vty_reference_combine.sh b/build/vty_reference_combine.sh index 6ab279e..7b19758 100755 --- a/build/vty_reference_combine.sh +++ b/build/vty_reference_combine.sh @@ -1,12 +1,9 @@ #!/bin/sh # usage: vty_reference_combine.sh path/to/merge_doc.xsl path/to/*reference.xml [paths to additional xmls] +# the result of combination is printed to stdout # see Makefile.vty-reference.inc set -e -# Allow overriding the "generated" output dir, so we don't have collisions when building multiple VTY references in one -# Osmocom project (OS#4292) -VTYGEN=${VTYGEN:-generated} - # first argument: merge_doc.xsl MERGE_DOC="$1" shift @@ -16,26 +13,29 @@ reference="$1" test "$(ls -1 $reference | wc -l)" = "1" shift -combined="$VTYGEN/combined.xml" -combine_src="$VTYGEN/combine_src.xml" - set -x -mkdir -p "$VTYGEN" -cp $reference "$combined" + +# we cannot use the same file as input and output, because +# xsltproc would override the input immediately :/ +combined=$(mktemp) +combine_src=$(mktemp) +cp $reference $combined while [ -n "$1" ]; do addition="$(realpath "$1")" shift - # Fix permissions: xsltproc sets the output permissions the same as the - # input file, which means during "make distcheck" our output file will - # become read-only. - if [ -f "$combine_src" ]; then - chmod 644 "$combine_src" - fi + # sync both input and output files + cp $combined $combine_src - mv "$combined" "$combine_src" xsltproc -o "$combined" \ --stringparam with "$addition" \ "$MERGE_DOC" "$combine_src" done + +# print the results to stdout +cat $combined >&1 + +# clean up temporary files +rm -f $combine_src +rm -f $combined 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 72578b9..9d635b0 100644 --- a/common/chapters/bibliography.adoc +++ b/common/chapters/bibliography.adoc @@ -3,121 +3,179 @@ == Appendix A. Bibliography / References [bibliography] +- [[[userman-ice1usb]]] Osmocom Project: icE1usb User Manual. +- [[[userman-ogt]]] Pau Espin: osmo-gsm-tester User Manual. +- [[[userman-remsim]]] Harald Welte: osmo-remsim User Manual. - [[[osmobts-abis-spec]]] Neels Hofmeyr & Harald Welte. OsmoBTS Abis Protocol Specification. - http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf -- [[[userman-osmobts]]] Osmocom Project: OsmoBTS User Manual. - http://ftp.osmocom.org/docs/latest/osmobts-usermanual.pdf -- [[[vty-ref-osmobts]]] Osmocom Project: OsmoBTS VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmobts-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-abis.pdf - [[[userman-osmobsc]]] Osmocom Project: OsmoBSC User Manual. - http://ftp.osmocom.org/docs/latest/osmobsc-usermanual.pdf + https://ftp.osmocom.org/docs/latest/osmobsc-usermanual.pdf - [[[vty-ref-osmobsc]]] Osmocom Project: OsmoBSC VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmobsc-vty-reference.pdf -- [[[userman-osmomsc]]] Osmocom Project: OsmoMSC User Manual. - http://ftp.osmocom.org/docs/latest/osmomsc-usermanual.pdf -- [[[vty-ref-osmomsc]]] Osmocom Project: OsmoMSC VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmomsc-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobsc-vty-reference.pdf +- [[[userman-osmobts]]] Osmocom Project: OsmoBTS User Manual. + https://ftp.osmocom.org/docs/latest/osmobts-usermanual.pdf +- [[[vty-ref-osmobts]]] Osmocom Project: OsmoBTS VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmobts-trx-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-sysmo-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-lc15-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-oc2g-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-octphy-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmobts-virtual-vty-reference.pdf +- [[[userman-osmocbc]]] Osmocom Project: OsmoCBC User Manual. + https://ftp.osmocom.org/docs/latest/osmocbc-usermanual.pdf +- [[[vty-ref-osmocbc]]] Osmocom Project: OsmoCBC VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmocbc-vty-reference.pdf +- [[[userman-osmogbproxy]]] Osmocom Project: OsmoGBProxy User Manual. + https://ftp.osmocom.org/docs/latest/osmogbproxy-usermanual.pdf +- [[[vty-ref-osmogbproxy]]] Osmocom Project: OsmoGBPRoxy VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmogbproxy-vty-reference.pdf +- [[[userman-osmoggsn]]] Osmocom Project: OpenGGSN User Manual. + https://ftp.osmocom.org/docs/latest/osmoggsn-usermanual.pdf +- [[[vty-ref-osmoggsn]]] Osmocom Project: OsmoGGSN VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmoggsn-vty-reference.pdf - [[[userman-osmohlr]]] Osmocom Project: OsmoHLR User Manual. - http://ftp.osmocom.org/docs/latest/osmohlr-usermanual.pdf + https://ftp.osmocom.org/docs/latest/osmohlr-usermanual.pdf - [[[vty-ref-osmohlr]]] Osmocom Project: OsmoHLR VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmohlr-vty-reference.pdf -- [[[userman-osmopcu]]] Osmocom Project: OsmoPCU User Manual. - http://ftp.osmocom.org/docs/latest/osmopcu-usermanual.pdf -- [[[vty-ref-osmopcu]]] Osmocom Project: OsmoPCU VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmopcu-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmohlr-vty-reference.pdf +- [[[userman-osmohnbgw]]] Osmocom Project: OsmoHNBGW User Manual. + https://ftp.osmocom.org/docs/latest/osmohnbgw-usermanual.pdf +- [[[vty-ref-osmohnbgw]]] Osmocom Project: OsmoHNBGW VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmohnbgw-vty-reference.pdf +- [[[userman-osmomgw]]] Osmocom Project: OsmoMGW User Manual. + https://ftp.osmocom.org/docs/latest/osmomgw-usermanual.pdf +- [[[vty-ref-osmomgw]]] Osmocom Project: OsmoMGW VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmomgw-vty-reference.pdf +- [[[userman-osmomsc]]] Osmocom Project: OsmoMSC User Manual. + https://ftp.osmocom.org/docs/latest/osmomsc-usermanual.pdf +- [[[vty-ref-osmomsc]]] Osmocom Project: OsmoMSC VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmomsc-vty-reference.pdf - [[[userman-osmonitb]]] Osmocom Project: OsmoNITB User Manual. - http://ftp.osmocom.org/docs/latest/osmonitb-usermanual.pdf + https://ftp.osmocom.org/docs/latest/osmonitb-usermanual.pdf - [[[vty-ref-osmonitb]]] Osmocom Project: OsmoNITB VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmonitb-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmonitb-vty-reference.pdf +- [[[userman-osmopcu]]] Osmocom Project: OsmoPCU User Manual. + https://ftp.osmocom.org/docs/latest/osmopcu-usermanual.pdf +- [[[vty-ref-osmopcu]]] Osmocom Project: OsmoPCU VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmopcu-vty-reference.pdf - [[[userman-osmosgsn]]] Osmocom Project: OsmoSGSN User Manual. - http://ftp.osmocom.org/docs/latest/osmosgsn-usermanual.pdf + https://ftp.osmocom.org/docs/latest/osmosgsn-usermanual.pdf - [[[vty-ref-osmosgsn]]] Osmocom Project: OsmoSGSN VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmonitb-vty-reference.pdf -- [[[userman-osmoggsn]]] Osmocom Project: OpenGGSN User Manual. - http://ftp.osmocom.org/docs/latest/osmoggsn-usermanual.pdf -- [[[vty-ref-osmoggsn]]] Osmocom Project: OsmoGGSN VTY Reference Manual. - http://ftp.osmocom.org/docs/latest/osmoggsn-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmosgsn-vty-reference.pdf +- [[[userman-osmosipconnector]]] Osmocom Project: OsmoSIPconnector User Manual. + https://ftp.osmocom.org/docs/latest/osmosipconnector-usermanual.pdf +- [[[vty-ref-osmosipconnector]]] Osmocom Project: OsmoSIPconnector VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmosipconnector-vty-reference.pdf +- [[[userman-osmosmlc]]] Osmocom Project: OsmoSMLC User Manual. + https://ftp.osmocom.org/docs/latest/osmosmlc-usermanual.pdf +- [[[vty-ref-osmosmlc]]] Osmocom Project: OsmoSMLC VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmosmlc-vty-reference.pdf +- [[[userman-osmostp]]] Osmocom Project: OsmoSTP User Manual. + https://ftp.osmocom.org/docs/latest/osmostp-usermanual.pdf +- [[[vty-ref-osmostp]]] Osmocom Project: OsmoSTP VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmostp-vty-reference.pdf +- [[[userman-osmotrx]]] Osmocom Project: OsmoTRX User Manual. + https://ftp.osmocom.org/docs/latest/osmotrx-usermanual.pdf +- [[[vty-ref-osmotrx]]] Osmocom Project: OsmoTRX VTY Reference Manual. + https://ftp.osmocom.org/docs/latest/osmotrx-uhd-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmotrx-lms-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmotrx-ipc-vty-reference.pdf + https://ftp.osmocom.org/docs/latest/osmotrx-usrp1-vty-reference.pdf +- [[[3gpp-ts-23-041]]] 3GPP TS 23.041: Technical realization of + Cell Broadcast Service (CBS) - [[[3gpp-ts-23-048]]] 3GPP TS 23.048: Security mechanisms for the (U)SIM application toolkit; Stage 2 - http://www.3gpp.org/DynaReport/23048.htm + https://www.3gpp.org/DynaReport/23048.htm - [[[3gpp-ts-23-236]]] 3GPP TS 23.236: Intra-domain connection of Radio Access Network (RAN) nodes to multiple Core Network (CN) nodes - http://www.3gpp.org/DynaReport/23236.htm + https://www.3gpp.org/DynaReport/23236.htm - [[[3gpp-ts-24-007]]] 3GPP TS 24.007: Mobile radio interface signalling layer 3; General Aspects - http://www.3gpp.org/DynaReport/24007.htm + https://www.3gpp.org/DynaReport/24007.htm - [[[3gpp-ts-24-008]]] 3GPP TS 24.008: Mobile radio interface Layer 3 specification; Core network protocols; Stage 3. - http://www.3gpp.org/dynareport/24008.htm + https://www.3gpp.org/dynareport/24008.htm - [[[3gpp-ts-31-101]]] 3GPP TS 31.101: UICC-terminal interface; Physical and logical characteristics - http://www.3gpp.org/DynaReport/31101.htm + https://www.3gpp.org/DynaReport/31101.htm - [[[3gpp-ts-31-102]]] 3GPP TS 31.102: Characteristics of the Universal Subscriber Identity Module (USIM) application - http://www.3gpp.org/DynaReport/31102.htm + https://www.3gpp.org/DynaReport/31102.htm - [[[3gpp-ts-31-103]]] 3GPP TS 31.103: Characteristics of the IMS Subscriber Identity Module (ISIM) application - http://www.3gpp.org/DynaReport/31103.htm + https://www.3gpp.org/DynaReport/31103.htm - [[[3gpp-ts-31-111]]] 3GPP TS 31.111: Universal Subscriber Identity Module (USIM) Application Toolkit (USAT) - http://www.3gpp.org/DynaReport/31111.htm + https://www.3gpp.org/DynaReport/31111.htm - [[[3gpp-ts-31-115]]] 3GPP TS 31.115: Secured packet structure for (Universal) Subscriber Identity Module (U)SIM Toolkit applications - http://www.3gpp.org/DynaReport/31115.htm + https://www.3gpp.org/DynaReport/31115.htm - [[[3gpp-ts-31-116]]] 3GPP TS 31.116: Remote APDU Structure for - (U)SIM Toolkit applications http://www.3gpp.org/DynaReport/31116.htm + (U)SIM Toolkit applications https://www.3gpp.org/DynaReport/31116.htm - [[[3gpp-ts-35-205]]] 3GPP TS 35.205: 3G Security; Specification of the MILENAGE algorithm set: General - [[[3gpp-ts-35-206]]] 3GPP TS 35.206: 3G Security; Specification of the MILENAGE algorithm set: Algorithm specification - http://www.3gpp.org/DynaReport/35206.htm + https://www.3gpp.org/DynaReport/35206.htm - [[[3gpp-ts-44-006]]] 3GPP TS 44.006: Mobile Station - Base Station System (MS - BSS) interface; Data Link (DL) layer specification - http://www.3gpp.org/DynaReport/44006.htm + https://www.3gpp.org/DynaReport/44006.htm - [[[3gpp-ts-44-018]]] 3GPP TS 44.018: Mobile radio interface layer 3 specification; Radio Resource Control (RRC) protocol - http://www.3gpp.org/DynaReport/44018.htm + https://www.3gpp.org/DynaReport/44018.htm - [[[3gpp-ts-44-064]]] 3GPP TS 44.064: Mobile Station - Serving GPRS Support Node (MS-SGSN); Logical Link Control (LLC) Layer Specification - http://www.3gpp.org/DynaReport/44064.htm + https://www.3gpp.org/DynaReport/44064.htm +- [[[3gpp-ts-45-002]]] 3GPP TS 45.002: Digital cellular telecommunications + system (Phase 2+) (GSM); GSM/EDGE Multiplexing and multiple access on the + radio path + https://www.3gpp.org/DynaReport/45002.htm - [[[3gpp-ts-48-008]]] 3GPP TS 48.008: Mobile Switching Centre - Base Station system (MSC-BSS) interface; Layer 3 specification - http://www.3gpp.org/DynaReport/48008.htm + https://www.3gpp.org/DynaReport/48008.htm - [[[3gpp-ts-48-016]]] 3GPP TS 48.016: General Packet Radio Service (GPRS); Base Station System (BSS) - Serving GPRS Support Node (SGSN) interface; Network service - http://www.3gpp.org/DynaReport/48016.htm + https://www.3gpp.org/DynaReport/48016.htm - [[[3gpp-ts-48-018]]] 3GPP TS 48.018: General Packet Radio Service (GPRS); Base Station System (BSS) - Serving GPRS Support Node (SGSN); BSS GPRS protocol (BSSGP) - http://www.3gpp.org/DynaReport/48018.htm + 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 - http://www.3gpp.org/DynaReport/48056.htm + https://www.3gpp.org/DynaReport/48056.htm - [[[3gpp-ts-48-058]]] 3GPP TS 48.058: Base Station Controller - Base Transceiver Station (BSC - BTS) Interface; Layer 3 specification - http://www.3gpp.org/DynaReport/48058.htm + https://www.3gpp.org/DynaReport/48058.htm - [[[3gpp-ts-51-011]]] 3GPP TS 51.011: Specification of the Subscriber Identity Module - Mobile Equipment (SIM-ME) interface - [[[3gpp-ts-51-014]]] 3GPP TS 51.014: Specification of the SIM Application Toolkit for the Subscriber Identity Module - Mobile - Equipment (SIM - ME) interface http://www.3gpp.org/DynaReport/51014.htm + Equipment (SIM - ME) interface https://www.3gpp.org/DynaReport/51014.htm - [[[3gpp-ts-52-021]]] 3GPP TS 52.021: Network Management (NM) procedures and messages on the A-bis interface - http://www.3gpp.org/DynaReport/52021.htm + https://www.3gpp.org/DynaReport/52021.htm - [[[etsi-tr102216]]] ETSI TR 102 216: Smart cards - http://www.etsi.org/deliver/etsi_tr/102200_102299/102216/03.00.00_60/tr_102216v030000p.pdf + https://www.etsi.org/deliver/etsi_tr/102200_102299/102216/03.00.00_60/tr_102216v030000p.pdf - [[[etsi-ts102221]]] ETSI TS 102 221: Smart Cards; UICC-Terminal interface; Physical and logical characteristics - http://www.etsi.org/deliver/etsi_ts/102200_102299/102221/13.01.00_60/ts_102221v130100p.pdf + https://www.etsi.org/deliver/etsi_ts/102200_102299/102221/13.01.00_60/ts_102221v130100p.pdf - [[[etsi-ts101220]]] ETSI TS 101 220: Smart Cards; ETSI numbering system for telecommunication application providers - http://www.etsi.org/deliver/etsi_ts/101200_101299/101220/12.00.00_60/ts_101220v120000p.pdf + https://www.etsi.org/deliver/etsi_ts/101200_101299/101220/12.00.00_60/ts_101220v120000p.pdf + +- [[[ieee-802.1q]]] IEEE 802.1Q: Bridges and Bridged Networks + https://ieeexplore.ieee.org/document/6991462 -- [[[ietf-rfc768]]] IETF RFC 768: Internet Protocol +- [[[ietf-rfc768]]] IETF RFC 768: User Datagram Protocol + https://tools.ietf.org/html/rfc768 +- [[[ietf-rfc791]]] IETF RFC 791: Internet Protocol https://tools.ietf.org/html/rfc791 - [[[ietf-rfc793]]] IETF RFC 793: Transmission Control Protocol https://tools.ietf.org/html/rfc793 @@ -127,6 +185,9 @@ https://tools.ietf.org/html/rfc1350 - [[[ietf-rfc2131]]] IETF RFC 2131: Dynamic Host Configuration Protocol https://tools.ietf.org/html/rfc2131 +- [[[ietf-rfc2474]]] IETF RFC 2474: Definition of the Differentiated Services Field (DS Field) in the IPv44 + and IPv6 Headers + https://tools.ietf.org/html/rfc2474 - [[[ietf-rfc2719]]] IETF RFC 2719: Signal Transport over IP https://tools.ietf.org/html/rfc2719 - [[[ietf-rfc3331]]] IETF RFC 3331: Message Transfer Part 2 User Adaptation Layer @@ -160,9 +221,9 @@ - [[[smpp-34]]] SMPP Develoepers Forum. Short Message Peer-to-Peer Protocol Specification v3.4 - http://docs.nimta.com/SMPP_v3_4_Issue1_2.pdf + https://docs.nimta.com/SMPP_v3_4_Issue1_2.pdf - [[[gnu-agplv3]]] Free Software Foundation. GNU Affero General Public - License. http://www.gnu.org/licenses/agpl-3.0.en.html + License. https://www.gnu.org/licenses/agpl-3.0.en.html - [[[freeswitch_pbx]]] FreeSWITCH SIP PBX https://freeswitch.org 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/control_if.adoc b/common/chapters/control_if.adoc index 67ac045..e64f661 100644 --- a/common/chapters/control_if.adoc +++ b/common/chapters/control_if.adoc @@ -188,7 +188,7 @@ Another implementation is in `scripts/osmo_rate_ctr2csv.py` which will retrieve for a given Osmocom program and output it in csv format. This can be used to periodically (using systemd timer for example) retrieve data to build KPI and evaluate how it changes over time. -Internally it uses "+rate_ctr.*+" variable described in <<ctrl_common_var>> to get the list of counter groups +Internally it uses "+rate_ctr.*+" variable described in <<ctrl_common_vars>> to get the list of counter groups and than request all the counters in each group. Applications interested in individual metrics can request it directly using `rate_ctr2csv.py` as an example. 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 c489883..09b526c 100644 --- a/common/chapters/cs7-config.adoc +++ b/common/chapters/cs7-config.adoc @@ -6,6 +6,10 @@ expecting to connect to a Signalling Gateway (STP/SG) implementing the M3UA SG role as SCTP server. The STP/SG then routes M3UA messages between its ASPs, typically by point-codes. +For an introduction about SCCP/M3UA/SS7/SIGTRAN technology, please see +the chapter _Signaling Networks: SS7 and SIGTRAN_ in the OsmoSTP user +manual. + In an all-Osmocom CNI, the typical simple/minimal usage is: - OsmoSTP acts as the STP/SG (server role) and routes between the ASP, @@ -46,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 @@ -57,11 +62,20 @@ At the time of writing, SCCP/M3UA links involving Osmocom program are: - A-interface: OsmoBSC to OsmoMSC - IuCS-interface: OsmoHNBGW to OsmoMSC - IuPS-interface: OsmoHNBGW to OsmoSGSN +- Lb-interface: OsmoSMLC to OsmoBSC -=== Connect to STP Instance +On the SCTP/IP level, those connections are actually all established from +the respective program (BSC, MSC, HNBGW, SGSN, SMLC) to OsmoSTP. Hence, +if you look at the traffic in a protocol analyzer like wireshark, at IP +level, you will see each of those programs establishing an SCTP +association from a random local IP to the well-known SCTP port for M3UA +(2905) at the OsmoSTP. -By default, an STP instance is assumed to listen on the default M3UA port -(2905) on the local host (127.0.0.1). +Those star-connections for M3UA/SCTP then are the transport network for +higher level protocols like SCCP. OsmoSTP then acts as central router +for SCCP-level message exchange between all the connected programs. + +=== Connect to STP Instance Establishing an SCCP/M3UA link towards a remote STP instance can be configured as: @@ -73,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, @@ -209,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 @@ -225,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 ---- @@ -235,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 @@ -291,3 +325,29 @@ routing-key RCONTEXT DPC si (aal2|bicc|b-isup|h248|isup|sat-isup|sccp|tup) routing-key RCONTEXT DPC ssn SSN routing-key RCONTEXT DPC si (aal2|bicc|b-isup|h248|isup|sat-isup|sccp|tup) ssn SSN ---- + +==== M3UA without Routing Context IE / Routing Context '0' + +As per the M3UA specification, the use of the routing context IE is +optional as long as there is only one AS within an ASP. As soon as +there are multiple different AS within one ASP, the routing context IE +is mandatory, as it is the only clue to differentiate which of the ASs a +given message belongs to. + +In the Osmocom M3UA implementation, it is generally assumed that a +routing context IE is always used, for the sake of clarity. + +However, the routing context ID of '0' has the special meaning of _do +not encode a routing context IE on transmit_. + +So if you configure an application like OsmoBSC to use routing context +0, then no routing context IE will be included in outbound M3UA +messages. + +This special interpretation of '0' within the Osmocom M3UA +implementation however means that we can not represent M3UA with a +routing context IE that actually contains '0' as a numeric identifier. + +So you only have the following options: +* Using M3UA with routing context (1..N) +* Using M3UA without routing context (0) diff --git a/common/chapters/gb-ip-sns.msc b/common/chapters/gb-ip-sns.msc new file mode 100644 index 0000000..f3fc2c4 --- /dev/null +++ b/common/chapters/gb-ip-sns.msc @@ -0,0 +1,38 @@ +msc { + hscale="2"; + pcu [label="PCU"], sgsn [label="SGSN"]; + + |||; + pcu rbox sgsn [label="(1) Initial Configuration after [re] start of PCU with NSEI 1024"]; + --- [label="SNS-Size procedure to inform SGSN of PCU NS-VC capacity"]; + pcu -> sgsn [label="SNS-SIZE (NSEI=1234, MAX-NR-NSVCS=8, NUM-IP-EP=1)"]; + pcu <- sgsn [label="SNS-SIZE-ACK (NSEI=1234)"]; + --- [label="PCU-originated SNS-CONFIG: Configure SGSN downlink flows"]; + pcu -> sgsn [label="SNS-CONFIG (NSEI=1234, List of PCU side IPv4/IPv6 Elements)"]; + pcu <- sgsn [label="SNS-CONFIG-ACK"]; + --- [label="SGSN-originated SNS-CONFIG: Configure PCU uplink flows"]; + pcu <- sgsn [label="SNS-CONFIG (NSEI=1234, List of SGSN side IPv4/IPv6 Elements)"]; + pcu -> sgsn [label="SNS-CONFIG-ACK"]; + |||; + pcu rbox sgsn [label="(2) Establishment of full mesh of NS-VCs: Each PCU side EP to each SGSN side EP"]; + --- [label="NS-ALIVE procedure to the first SGSN-side IPv4 Endpoint"]; + pcu -> sgsn [label="NS-ALIVE"]; + pcu <- sgsn [label="NS-ALIVE-ACK"]; + --- [label="NS-ALIVE procedure to the second SGSN-side IPv4 Endpoint"]; + pcu -> sgsn [label="NS-ALIVE"]; + pcu <- sgsn [label="NS-ALIVE-ACK"]; + |||; + pcu rbox sgsn [label="(3) Establishment of BSGGP Virtual Connections (BVC)"]; + --- [label="BVC-RESET of the (PCU global) Signaling BVC"]; + pcu -> sgsn [label="NS-UNITDATA( BVC-RESET (BVCI=0) )"]; + pcu <- sgsn [label="NS-UNITDATA( BVC-RESET-ACK (BVCI=0) )"]; + |||; + --- [label="BVC-RESET of the PTP BVC of the first cell in the BSS"]; + pcu -> sgsn [label="NS-UNITDATA( BVC-RESET (BVCI=999, RA-ID 262-42-13135-0) )"]; + pcu <- sgsn [label="NS-UNITDATA( BVC-RESET-ACK (BVCI=999) )"]; + ...; + --- [label="BVC-RESET of the PTP BVC of the Nth cell in the BSS"]; + pcu -> sgsn [label="NS-UNITDATA( BVC-RESET (BVCI=543, RA-ID 262-42-24675-0) )"]; + pcu <- sgsn [label="NS-UNITDATA( BVC-RESET-ACK (BVCI=543) )"]; + +} 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 new file mode 100644 index 0000000..e72fa50 --- /dev/null +++ b/common/chapters/gb-ns2.adoc @@ -0,0 +1,498 @@ +== Gb/NS Network Service + +'libosmogb' is part of the libosmocore.git repository and implements the +Gb interface protocol stack consisting of the NS and BSSGP layers. It +is used in a variety of Osmocom projects, including OsmoSGSN, OsmoPCU +and OsmoGbProxy. + +NOTE: <<3gpp-ts-48-016>> specifies Network Service + +[[gb_variants]] +=== Gb interface variants + +There are multiple variants of the Gb interface. This +section tries to provide an overview into what those variants are, how +they differ from each other. + +The two peers involved in any Gb interface must always be in agreement +about the specific Gb interface variant before they are able to +connect. + +The following variants are supported by Osmocom: + +* Gb-over-Frame-Relay over E1/T1 +* Gb-over-IP "ip.access style" +* Gb-over IP 3GPP static configuration +* Gb-over-IP 3GPP auto-configuration + +[[gb-fr]] +==== Gb over Frame Relay over E1/T1 + +Historically, this is the first Gb interface that was specified as part +of GSM Release 97 when GPRS was first introduced. + +Like all other terrestrial GSM interfaces, it uses circuit-switched +technology from the PDH/ISDN family of systems: E1 or T1 lines as per +ITU-T G.703 / G.704. + +GSM TS 08.16 and later <<3gpp-ts-48-016>> specify that Frame Relay (FR) +shall be used as transport layer between the E1/T1 bit-stream and the +NS-level Gb messages. + +Two peer entities such as a GPRS BSS and a SGSN are interconnected by a +NS-VCG (Virtual Connection Group) consisting of any number of NS-VCs +(Virtual Connections). + +Each NS-VC in turn operates over a Frame Relay Permanent Virtual Circuit +(PVC), identified by its DLCI (Data Link Connection Identifier). + +The protocol stacking is BSSGP/NS/FR/E1. + + +===== FR Driver Support + +The Osmocom NS/FR implementation currently requires the individual Frame Relay +Links to be exposed as Linux kernel HDLC net-devices. The Osmocom NS +implementation has to be instructed which `hdlcX` network devices it +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 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 + `ip link set hdlcX up` command. + +As the Osmocom Gb implementation uses AF_PACKET sockets on those +`hdlcX` network interfaces, the respective program must be running with +`CAP_NET_RAW` capability. + +[[gb-gre-fr]] +==== Gb over Frame Relay encapsulated in GRE/IP + +This is a variant of the Gb-over-FR specified above. However, an +external router (e.g. certain ancient Cisco routers) is used to take the +Frame Relay frames from the physical E1/T1 TDM circuit and wrap them +into the GRE encapsulation as per IETF RFC 2784. + +NOTE: GRE/IP has been removed from Osmocom NS code. + +[[gb-ip-access]] +==== Gb over IP "ip.access style" + +This is a non-standard variant of Gb which is not found in the GSM/3GPP +specifications. + +It uses an UDP/IP based transport layer, while not yet implementing the +IP-SNS that is normally required by a true 3GPP Gb over IP interface +described further below. Hence, this variant resembles an intermediate +state where a Gb interface originally designed for Frame Relay is used +over IP without any of the IP-specific procedures specified by 3GPP. + +The major difference to 3GPP Gb over IP specified below are: + +* No support for the IP-SNS and its SNS-SIZE, SNS-ADD, SNS-DELETE, + SNS-WEIGHT procedures. +* Use of the NS-RESET, NS-BLOCK and NS-UNBLOCK procedures which are + normally forbidden over an IP network. + +The protocol stacking is BSSGP/NS/UDP/IP. + +[[gb-ip-sns]] +==== Gb over IP 3GPP static and auto-configuration + +This is the only official, 3GPP-standardized way of speaking a Gb +interface over IP based transport. + +It features the IP Sub-Network Service (IP-SNS) which allows either +static configuration or dynamic configuration. +The static configuration requires to specify the NSE and related NS-VC +configuration via VTY similiar to Gb-over-FR. + +===== Gb over IP 3GPP auto-configuration + +The auto-configuration allow to dynamically exchange information about +IP endpoints (IP+port tuples) between the Gb interface peers. +This means that normally only one initial IP endpoint needs to be configured. +All additional IP endpoints and their relative weight for load distribution are then negotiated via the +IP-SNS auto-configuration procedure. + +The major differences of this true IP based Gb compared to any of the +above are: + +* No use of the NS-RESET, NS-BLOCK or NS-UNBLOCK procedures. +* Ability to use some NS-VCs only for signaling (data_weight=0) or only + for user plane traffic (signaling_weight=0). This helps with SGSNs + that have an internal control/user plane separation architecture. + +Once the IP endpoints of the peers are known to each other, A full mesh +of NS-VCs between all BSS endpoints and all SGSN endpoints is +established. + +<<fig-gb-sns-nsvcs>> below illustrates a deployment with two IP +endpoints on both the BSS (PCU) and the SGSN, as well as the resulting +four NS-VCs established between them. + +[[fig-gb-sns-nsvcs]] +.IP sub-network relationship between NS-VCs and NS-VLs (from 3GPP TS 48.016) +image::./common/images/gb-ip-nsvc.pdf[] + +The sequence of messages in an IP-SNS enabled Gb interface bring-up can +be seen in <<fig-ip-sns-sequence>>. Here we have a PCU/BSS with a +single IP endpoint and a SGSN with two IP endpoints, which results in +only two NS-VC being established. + +Furthermore, for each of the cells in the BSS/PCU, we can see the +BVC-RESET procedure for its corresponding PTP BVC. + +[[fig-ip-sns-sequence]] +.Initialization of Gb interface using IP-SNS procedures +[mscgen] +---- +include::gb-ip-sns.msc[] +---- + +=== General structure + +The general structure of the configuration is split into 3 parts + +* binds (NS-VL) +* nse (NS-E) +* timeouts + +==== bind (NS-VL) + +A bind represent a NS-VL. A bind has a specific type (IP/UDP or FR) +and a unique name. + +==== NS-E + +A NSE node represents a NS Entity. A NSE is either persistent or dynamic. +A persistent NSE is configured by VTY. A dynamic NSE is created on-demand +without any VTY node. The SGSN/GbProxy creates dynamic NSE when a BSS connects +to the SGSN (see accept-ipaccess). +The PCU creates a dynamic NSE when it receives the configuration from BTS/BSC. + +==== NS-VC + +A NS-VC is always bound to a NSE and the bind (NS-VL). The NSVC can be either +persistent or dynamic. + + +=== 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 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/gb-pool.adoc b/common/chapters/gb-pool.adoc new file mode 100644 index 0000000..1a9fb87 --- /dev/null +++ b/common/chapters/gb-pool.adoc @@ -0,0 +1,62 @@ +[[gb-sgsn-pool]] +== Gb interface in SGSN Pooling + +SGSN Pooling is a modern optional extension of the 3GPP GERAN +architecture. It is officially referred-to as _Intra Domain Connection +of RAN Nodes to Multiple CN Nodes_. It requires The use of IP-SNS and +does not support legacy or non-standard Gb variants. + +Without this optional feature, a given PCU/BSS always connects to one +SGSN via a Gb interface. All traffic is handled through that one +interface. + +While the NS-level load sharing function and the _weights_ of the IP-SNS +allow for load distribution between different user plane entities, there +was demand for additional scalability and fail-over capabilities leading +to the SGSN pooling feature. + +The major changes introduced to the Gb interface by SGSN pooling are as +follows: + +* There is a separate NSE in the BSS for each of the SGSNs in the pool, + creating a 1:1 relationship between BSS-NSE and SGSN. +* Each of those per-SGSN NSEs has it's own NS-VCGs and NS-VCs, unrelated + to those of the other NSEs +* Each of those per-SGSN NSEs has it's own Signaling BVC +* Each Cell in the BSS has one PTP BVC _per SGSN in the pool_ + +This relationship is illustrated in <<fig-gb-pool>> below. + +[[fig-gb-pool]] +.Gb interface concepts when SGSN pooling feature is used (from 3GPP TS 48.016) +image::./common/images/gb-concepts-pool.pdf[] + +Looking strictly at the Gb interface, this means that there is a completely +separate Gb interface between each BSS and each pool member SGSN. All of the +procedures explained in <<gb-ip-sns>> hence occur N number of times to N number +of SGSN pool members. + +=== Status of SGSN Pool support in Osmocom + +==== osmo-pcu + +There is currently no direct support for SGSN pooling in `osmo-pcu` +itself. However, as of December 2020, `osmo-gbproxy` is being extended +with SGSN pooling support. + +This means that SGSN pooling can be added to any `osmo-pcu` based +deployment by introducing `osmo-gbproxy` between `osmo-pcu` and the SGSN. + +The use of `osmo-gbproxy` also has the added benefit that all Gb +interfaces from various PCUs are aggregated into one Gb interface +towards (each) SGSN. Most deployments are used to such a _one interface +per BSS_ approach as they are used to the BSC-colocated PCU architecture +and not to the BTS-colocated PCU architecture as implemented in Osmocom. + +==== osmo-gbproxy + +FIXME + +==== osmo-sgsn + +FIXME 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 d6a6c2d..bbddcc5 100644 --- a/common/chapters/glossary.adoc +++ b/common/chapters/glossary.adoc @@ -30,6 +30,8 @@ AGCH:: channel in response to RACH request AGPL:: GNU Affero General Public License, a copyleft-style Free Software License +AQPSK:: + Adaptive QPSK, a modulation scheme used by VAMOS channels on Downlink ARFCN:: Absolute Radio Frequency Channel Number; specifies a tuple of uplink and downlink frequencies @@ -51,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:: @@ -75,10 +83,12 @@ dBm:: deci-Bel (milliwatt); unit of measurement for signal strength of radio signals DHCP:: - Dynamic Host Configuration Protocol (_IETF RFC 2131_ <<ietf-rfc2131>> + Dynamic Host Configuration Protocol (_IETF RFC 2131_ <<ietf-rfc2131>>) downlink:: Direction of messages / signals from the network core towards the mobile phone +DSCP:: + Differentiated Services Code Point (_IETF RFC 2474_ <<ietf-rfc2474>>) DSP:: Digital Signal Processor dvnixload:: @@ -126,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:: @@ -262,6 +272,8 @@ PC:: Point Code; an address in MTP PCH:: Paging Channel on downlink Um interface; used by network to page an MS +PCP:: + Priority Code Point (_IEEE 802.1Q_ <<ieee-802.11>>) PCU:: Packet Control Unit; used to manage Layer 2 of the GPRS radio interface PDCH:: @@ -352,6 +364,8 @@ TCP:: Transmission Control Protocol; (_IETF RFC 793_ <<ietf-rfc793>>) TFTP:: Trivial File Transfer Protocol; (_IETF RFC 1350_ <<ietf-rfc1350>>) +TOS:: + Type Of Service; bit-field in IPv4 header, now re-used as DSCP (_IETF RFC 791_ <<ietf-rfc791>>) TRX:: Transceiver; element of a BTS serving a single carrier TS:: @@ -377,10 +391,17 @@ USIM:: USSD:: Unstructured Supplementary Service Data; textual dialog between subscriber and core network, e.g. '*#100#' -> 'Your extension is 1234' +VAMOS:: + Voice services over Adaptive Multi-user channels on One Slot; an optional + extension for GSM specified in Release 9 of 3GPP GERAN specifications + (_3GPP TS 48.018_ <<3gpp-ts-48-018>>) allowing two independent UEs to + transmit and receive simultaneously on traffic channels VCTCXO:: Voltage Controlled, Temperature Compensated Crystal Oscillator; a precision oscillator, superior to a classic crystal oscillator, but inferior to an OCXO +VLAN:: + Virtual LAN in the context of Ethernet (_IEEE 802.1Q_ <<ieee-802.1q>>) VLR:: Visitor Location Register; volatile storage of attached subscribers in the MSC 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 11ec774..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 @@ -290,6 +306,84 @@ with a time-stamp, so you should disable the libosmocore time-stamping by issuing the `logging timestamp 0` command. +==== Logging to systemd-journal + +systemd has been adopted by the majority of modern GNU/Linux distributions. +Along with various daemons and utilities it provides systemd-journald [1] - +a daemon responsible for event logging (syslog replacement). libosmocore +based applications can log messages directly to systemd-journald. + +The key difference from other logging targets is that systemd based logging +allows to offload rendering of the meta information, such as location +(file name, line number), subsystem, and logging level, to systemd-journald. +Furthermore, systemd allows to attach arbitrary meta fields to the logging +messages [2], which can be used for advanced log filtering. + +[1] https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html +[2] https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html + +It was decided to introduce libsystemd as an optional dependency, +so it needs to be enabled explicitly at configure/build time: + +---- +$ ./configure --enable-systemd-logging +---- + +NOTE: Recent libosmocore packages provided by Osmocom for Debian and CentOS are +compiled *with* libsystemd (https://gerrit.osmocom.org/c/libosmocore/+/22651). + +You can configure systemd based logging in two ways: + +.Example: `systemd-journal` target with offloaded rendering +---- +log systemd-journal raw <1> + logging filter all 1 + logging level set-all notice +---- +<1> `raw` logging handler, rendering offloaded to systemd. + +In this example, logging messages will be passed to systemd without any meta +information (time, location, level, category) in the text itself, so all +the printing parameters like `logging print file` will be ignored. Instead, +the meta information is passed separately as _fields_ which can be retrieved +from the journal and rendered in any preferred way. + +---- +# Show Osmocom specific fields +$ journalctl --fields | grep OSMO + +# Filter messages by logging subsystem at run-time +$ journalctl OSMO_SUBSYS=DMSC -f + +# Render specific fields only +$ journalctl --output=verbose \ + --output-fields=SYSLOG_IDENTIFIER,OSMO_SUBSYS,CODE_FILE,CODE_LINE,MESSAGE +---- + +See `man 7 systemd.journal-fields` for a list of default fields, and +`man 1 journalctl` for general information and available formatters. + +.Example: `systemd-journal` target with libosmocore based rendering +---- +log systemd-journal <1> + logging filter all 1 + logging print file basename + logging print category-hex 0 + logging print category 1 + logging print level 1 + logging timestamp 0 <2> + logging color 1 <3> + logging level set-all notice +---- +<1> Generic logging handler, rendering is done by libosmocore. +<2> Disable timestamping, systemd will timestamp every message anyway. +<3> Colored messages can be rendered with `journalctl --output=cat`. + +In this example, logging messages will be pre-processed by libosmocore before +being passed to systemd. No additional fields will be attached, except the +logging level (`PRIORITY`). This mode is similar to _syslog_ and _stderr_. + + ==== Logging to stderr If you're not running the respective application as a daemon in the 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 48ba7a2..16b9ce3 100644 --- a/common/chapters/port_numbers.adoc +++ b/common/chapters/port_numbers.adoc @@ -10,10 +10,13 @@ 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 |TCP|3003|A-bis/IP RSL|osmo-bts, osmo-bsc, osmo-nitb +|TCP|4227|telnet (VTY)|osmo-pcap-client +|TCP|4228|telnet (VTY)|osmo-pcap-server |TCP|4236|Control Interface|osmo-trx |TCP|4237|telnet (VTY)|osmo-trx |TCP|4238|Control Interface|osmo-bts @@ -48,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 new file mode 100644 index 0000000..81a9e4e --- /dev/null +++ b/common/chapters/qos-dscp-pcp.adoc @@ -0,0 +1,161 @@ +[[qos-dscp-pcp]] +== QoS, DSCP/TOS, Priority and IEEE 802.1q PCP + +In many use cases operators want to apply different QoS classes for user plane +vs. control plane traffic. IP Routers, Ethernet switches and other network gear +can then perform intelligent queue management as required for the respective service. + +For example, voice user plane frames need a rather stable and short latency, +while IP user plane and control plane traffic has less critical latency requirements. + +=== IP Level (DSCP) + +At IP level, different priorities / classes of traffic are expressed +in accordance to <<ietf-rfc2474>> by the DSCP (Differentiated Services Code +Point) field of the IP header. DSCP resembles the upper 6 bits of the +field formerly known as the TOS bits as per <<ietf-rfc791>>. + +On Linux and other operating systems with BSD-style sockets API, the +applications can request a specific DSCP value to be used for packets +generated by those sockets. + +Osmocom CNI software such as osmo-bts and osmo-mgw support setting the +DSCP value via VTY commands, see e.g. the `rtp ip-dscp` setting of the +`bts` node in osmo-bts. + + +=== Packet Priority + +In the Linux network stack, every packet is represented by `struct +sk_buff`, which has an associated _priority_. Furthermore, every socket +through which applications send data have an associated _socket +priority_. Each time a packet is transmitted through a given socket, +the packet inherits the packet priority from the socket priority. + +Furthermore, there is a mapping table that maps DSCP/TOS bits to +priority. The sixteen different TOS bit values are mapped to priority +values as follows: + +.Linux kernel default DSCP/TOS -> priority mapping +[options="header",width="50%"] +|=== +|TOS (binary)|DSCP (binary)|Priority (decimal) +|xxx0000x|xxx000|0 +|xxx0001x|xxx000|0 +|xxx0010x|xxx001|0 +|xxx0011x|xxx001|0 +|xxx0100x|xxx010|2 +|xxx0101x|xxx010|2 +|xxx0110x|xxx011|2 +|xxx0111x|xxx011|2 +|xxx1000x|xxx100|6 +|xxx1001x|xxx100|6 +|xxx1010x|xxx101|6 +|xxx1011x|xxx101|6 +|xxx1100x|xxx110|4 +|xxx1101x|xxx110|4 +|xxx1110x|xxx111|4 +|xxx1111x|xxx111|4 +|=== + +This table of default DSCP/TOS -> priority bit mappings cannot be +modified. + +However, the per-packet _priority_ values can be set by various means +of network policy, including + +* by packet filter rules (iptables, ip6tables, nftables) +** if you use `iptables`, using `CLASSIFY --set-class` in the `mangle` table +** if you use `nftables`, using `meta priority set` in the `mangle` table +* by the application using the SO_PRIORITY socket option (currently not yet supported by Osmocom CNI) + + +=== Ethernet Level (PCP) + +At Ethernet level, different priorities / QoS classes are expressed by +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. + +The Linux kernel assigns IEEE 802.1q PCP bits based on a _mapping_ +between the _priority_ and the PCP value. Each VLAN network device +maintains a separate map for both egress (transmit) and ingress +(receive) path. + +The current priority mappings can be inspected via the `/proc` +filesystem. For example, if you have a VLAN device `eth0.9` for +VLAN ID 9 on the net-device `eth0`, you can use the following example: + +.Example: Inspecting the current egress QoS map +---- +$ sudo cat /proc/net/vlan/eth0.9<1> +eth0.9 VID: 9 REORDER_HDR: 1 dev->priv_flags: 1021 + total frames received 123340 + total bytes received 40668066 + Broadcast/Multicast Rcvd 1106 + + total frames transmitted 10499 + total bytes transmitted 1570809 +Device: eth0 +INGRESS priority mappings: 0:0 1:0 2:0 3:0 4:0 5:0 6:0 7:0 <2> + EGRESS priority mappings: <3> +---- +<1> make sure to specify your specific VLAN interface name here instead of `eth0.9` +<2> ingress priority mappings (all PCP values mapped to priority 0) +<3> egress priority mappings (empty) + +As we can see in the above example, there are no egress priority +mappings yet. Let's create three new mappings, mapping _priority_ +value 1 to PCP 1, _priority_ 2 to PCP 2, and _priority_ 3 to PCP 3: + +.Example: Creating three new egress QoS mappings +---- +$ sudo ip link set dev eth0.9<1> type vlan egress-qos-map 1:1 2:2 3:3 <2> +$ sudo cat /proc/net/vlan/eth0.9 <3> +eth0.9 VID: 9 REORDER_HDR: 1 dev->priv_flags: 1021 + total frames received 123898 + total bytes received 40843611 + Broadcast/Multicast Rcvd 1106 + + total frames transmitted 10517 + total bytes transmitted 1574357 +Device: eth0 +INGRESS priority mappings: 0:0 1:0 2:0 3:0 4:0 5:0 6:0 7:0 + EGRESS priority mappings: 1:1 2:2 3:3 <4> +---- +<1> make sure to specify your specific VLAN interface name here instead of `eth0.9` +<2> command to define three new egress QoS maps +<3> command to re-display the current status +<4> three new egress mappings are shown as given in `ip` command + +NOTE:: The settings of the `ip` command are volatile and only active until +the next reboot (or the network device or VLAN is removed). Please refer to +the documentation of your specific Linux distribution in order to find out how +to make such settings persistent by means of an `ifup` hook whenever the interface +comes up. For CentOS/RHEL 8 this can e.g. be achieved by means of an `/sbin/ifup-local +script` (when using `network-scripts` and not NetworkManager). For Debian or Ubuntu, +this typically involves adding `up` lines to `/etc/network/interfaces` or a `/etc/network/if-up.d` +script. + + +=== Putting things together + +Assuming one needs to set both the DSCP bits as well as the PCP for +certain traffic, the above-mentioned mechanisms need to be combined as +follows: + +. configure the osmocom program to set the DSCP value +. use the default DSCP -> priority mapping, if possible +. 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 +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 egress QoS map to map from priority to PCP + +include::{srcdir}/chapters/qos-example.adoc[] diff --git a/common/chapters/rf.adoc b/common/chapters/rf.adoc index f3f6dd9..637fb5e 100644 --- a/common/chapters/rf.adoc +++ b/common/chapters/rf.adoc @@ -45,7 +45,7 @@ So in order to estimate the loss of a coaxial cable, you need to . determine the frequency at which you will use the cable, as determined by the GSM frequency band of your BTS. Make sure you use the highest frequency that might occur, which is typically the upper end of the - transmit band, see <<gsm-bands>> + transmit band, see <<rf-gsm-bands>> . determine the attenuation of your cable per 100m at the given frequency (check the cable data sheet) . scale that value by the actual length of the cable 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 9e02f38..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) @@ -285,6 +285,9 @@ comprised of M3UA over SCTP over IP. M3UA is specified in <<ietf-rfc4666>>. +M3UA is the SIGTRAN variant chosen by 3GPP for A, IuCs and IuPS +interfaces over IP. + ===== SCCP User Adaptation (SUA) SUA basically "chops off" everything up to and including the SCCP @@ -330,3 +333,192 @@ SCTP (and thus all the higher layer protocols of the various SIGTRAN 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 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. + +Instead, SCTP creates _associations_ between two endpoints, both of which +can have any number of IP addresses. This means that in case of +network outage, traffic can continue to flow through any of the IP +addresses of that association. + +The Linux kernel by default advertises all IP addresses of the local +system to the peer. This can be seen when inspecting the SCTP INIT +chunk e.g. in wireshark. While this may be a reasonable default in some +use cases, it is not always the best idea. Imagine addresses of +internal/private IP networks, for example local bridge devices between +lxc or docker containers, or local VMs. Such addresses have no +significance beyond the local machine. + +Subsequently, libosmo-sigtran allows the user to explicitly select which +local IP addresses shall be used in SCTP multi-homing for the SIGTRAN +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: + +* The _SCTP server_ role binds to a local port and handles incoming + connections from clients +* The _SCTP client_ role connects to a remote SCTP sever. + +==== M3UA/SUA role + +The _M3UA role_ (or _SUA role_) determines which role a given peer of a +M3UA connection implements. 3GPP specifies the following role: + +* _SGP_ (Signaling Gateway): The entity connected to the larger SS7 + network +* _ASP_ (Application Server Process): A client application that connects + to the SGW to talk to the SS7 network +* _IPSP_ (IP Server Process): M3UA in point-to-point mode + +Osmocom (libosmo-sigtran) implements both the SGP and ASP roles, but not +the IPSP role. + +==== Traffic Modes in SIGTRAN + +Whenever an AS consists of multiple ASPs, the traffic mode expresses how +messages are distributed between those ASPs. + +* _Override_: There is always one active ASP and multiple hot standby + ASPs. If the active ASP fails, one of the remaining ASPs will become + the new active ASP. +* _Loadshare_: The messages will be distributed between the different + ASPs in a way to distribute the load among them. Details are + implementation specific. +* _Broadcast_: A copy of every incoming signaling message is sent to + _all_ the ASPs in broadcast traffic mode. + +Osmocom (libosmo-sigtran) implements all above-mentioned traffic modes. 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 f15ed7b..a7be07c 100644 --- a/common/chapters/trx_if.adoc +++ b/common/chapters/trx_if.adoc @@ -1,3 +1,7 @@ +// Common attributes (macros) used in this document +:bit-zero: '0\'B +:bit-one: '1\'B + [[trx_if]] == TRX Manager UDP socket interface @@ -18,6 +22,10 @@ a channel `0 <= X <= N` are: The corresponding interface for every socket is at `P+100` on the BTS side. +NOTE: Starting from TRXDv2, it's possible to use only one socket for all +channels. In this case, the global `TRXD` interface for all channels shall +be established on port `P=B+1`. See <<trx_if_pdu_batching>> for more details. + [[trx_if_clock_ind]] === Indications on the Master Clock Interface @@ -127,6 +135,20 @@ CMD TXTUNE <kHz> RSP TXTUNE <status> <kHz> ---- +==== Training Sequence configuration + +The usual way to configure all timeslots at once involves sending of the `SETTSC` +command with a desired Training Sequence Code `<tsc>`: +---- +CMD SETTSC <tsc> +CMD SETTSC <status> <tsc> +---- + +This command instructs the transceiver to use the given Training Sequence Code +from the TSC set 1 (see 3GPP TS 45.002, table 5.2.3a) for Normal Burst detection +on the receive path. It does not affect the transmit path because bursts coming +from the BTS do contain the Training Sequence bits. + ==== Timeslot Control `SETSLOT` sets the format of a given uplink timeslot in the ARFCN. @@ -160,15 +182,153 @@ Here's the list of channel combinations and related values (`<chantype>`): |13| PDTCH+PACCH+PTCCH |=== +===== Multiple Training Sequences (optional) + +For some setups it's insufficient to have a single Training Sequence Code assigned +to all timeslots of a transceiver. It may be required to use different TSCs for +some (or even all) timeslots. This can be achieved by sending `SETSLOT` command +with additional arguments: +---- +CMD SETSLOT <timeslot> <chantype> [ C<c>/S<s> ] +RSP SETSLOT <status> <timeslot> <chantype> [ C<c>/S<s> ] +---- + +where `<c>` is a Training Sequence Code from TSC set `<s>`. + +NOTE: The numbering of both Training Sequence Code and set shall be the same as in +3GPP TS 45.002, e.g. `C0S1` corresponds to the first sequence in the first TSC set +for a chosen modulation type. TSC Set number 0 (`S0`) does not exist in the specs. + +.Example: configuring timeslot 4 to use TCH/F and TSC 7 from set 1 +---- +CMD SETSLOT 4 1 C7/S1 +RSP SETSLOT 0 4 1 C7/S1 +---- + +Unless explicitly configured as described above, all timeslots will be using the +default Training Sequence Code and set configured with the `SETTSC` command. + +===== VAMOS enabled channel combinations (optional) + +The BTS may at any time re-configure channel combination of a timeslot (primarily +during channel activation) to activate or deactivate VAMOS mode in the transceiver. +For this purpose, the following additional channel combinations shall be used: + +.List of VAMOS enabled channel combinations and related values +[options="header"] +|=== +| value | Channel Combination +|VFF| V0(TCH/F) & V1(TCH/F), 2 channels total +|VHH| V0(TCH/H0) & V1(TCH/H0) + V0(TCH/H1) & V1(TCH/H1), 4 channels total +|VFH| V0(TCH/F) & V1(TCH/H0) + V0(TCH/F) & V1(TCH/H1), 3 channels total +|HVHH| TCH/H0 + V0(TCH/H1) & V1(TCH/H1), 3 channels total (mixed) +|=== + +where both `V0` and `V1` define a _VAMOS pair_. Symbols `&` and `+` indicate +simultaneous and sequential transmission in the TDMA domain respectively. +Therefore a combination `V0(a) & V1(b)` indicates that both channels `a` +and `b` are simultaneously active during a timeslot period. + +.Example: `VFF` in time domain (2 channels) +---- + MS1: | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | ... + -----+-----------+-----------+-----------+-----------+------------> TDMA frames + MS2: | V1(TCH/F) | V1(TCH/F) | V1(TCH/F) | V1(TCH/F) | ... +---- + +.Example: `VHH` in time domain (4 channels) +---- + MS1: | V0(TCH/H0) | | V0(TCH/H0) | | ... + MS2: | | V0(TCH/H1) | | V0(TCH/H1) | ... + -----+------------+------------+------------+------------+--------> TDMA frames + MS3: | V1(TCH/H0) | | V1(TCH/H0) | | ... + MS4: | | V1(TCH/H1) | | V1(TCH/H1) | ... +---- + +.Example: `VFH` in time domain (3 channels) +---- + MS1: | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | ... + -----+------------+------------+------------+------------+--------> TDMA frames + MS2: | V1(TCH/H0) | | V1(TCH/H0) | | ... + MS3: | | V1(TCH/H1) | | V1(TCH/H1) | ... +---- + +.Example: `HVHH` in time domain (3 channels) +---- + MS1: | TCH/H0 | | TCH/H0 | | ... + MS2: | | V0(TCH/H1) | | V0(TCH/H1) | ... + -----+------------+------------+------------+------------+--------> TDMA frames + MS3: | | V1(TCH/H1) | | V1(TCH/H1) | ... +---- + +NOTE: Combination `HVHH` is special, because it allows the network to multiplex +a legacy user device (`MS1`) with a pair of VAMOS capable devices (`MS2` and `MS3`) +on the same timeslot, so the former (`MS1`) is neither required to support the new +orthogonal TSC sets nor conform to DARP phase I or II (SAIC support). + +For all VAMOS enabled channel combinations, it's *required* to specify Training +Sequence Code and the TSC set values for all multiplexed subscribers. See 3GPP +TS 45.002, table 5.2.3e for more details on TSC set selection. + +.Example: configuring a timeslot to use `VFF` combination +---- +CMD SETSLOT <timeslot> VFF C0/S1 <1> C0/S2 <2> +RSP SETSLOT <status> <timeslot> VFF C0/S1 C0/S2 +---- +<1> V0(TCH/F) is configured to use TSC 0 from set 1 (table 5.2.3a). +<2> V1(TCH/F) is configured to use TSC 0 from set 2 (table 5.2.3b). + +.Example: configuring a timeslot to use `VFF` combination (legacy MS) +---- +CMD SETSLOT <timeslot> VFF C7/S1 <1> C4/S1 <2> +RSP SETSLOT <status> <timeslot> VFF C7/S1 C4/S1 +---- +<1> V0(TCH/F) is configured to use TSC 7 from set 1 (table 5.2.3a). +<2> V1(TCH/F) is configured to use TSC 4 from set 1 (table 5.2.3a). + +NOTE: Using Training Sequences from the same set for a _VAMOS pair_ (in this example, +`C7/S1 C4/S1`) is not recommended because of their bad cross-correlation properties. +The only exception is when two legacy non-VAMOS capable phones are paired together +and neither of them does support additional TSC sets. + +.Example: configuring a timeslot to use `VHH` combination +---- +CMD SETSLOT <timeslot> VHH C1/S3 <1> C1/S4 <2> +RSP SETSLOT <status> <timeslot> VHH C1/S3 C1/S4 +---- +<1> V0(TCH/H0) and V0(TCH/H1) are configured to use TSC 1 from set 3 (table 5.2.3c). +<2> V1(TCH/H0) and V1(TCH/H1) are configured to use TSC 1 from set 4 (table 5.2.3d). + +.Example: configuring a timeslot to use `VFH` combination +---- +CMD SETSLOT <timeslot> VFH C2/S1 <1> C2/S4 <2> +RSP SETSLOT <status> <timeslot> VFH C2/S1 C2/S4 +---- +<1> V0(TCH/F) is configured to use TSC 2 from set 1 (table 5.2.3a). +<2> V1(TCH/H0) and V1(TCH/H1) are configured to use TSC 2 from set 4 (table 5.2.3d). + +.Example: configuring a timeslot to use `HVHH` combination +---- +CMD SETSLOT <timeslot> HVHH C0/S1 <1> C0/S1 <2> C0/S2 <3> +RSP SETSLOT <status> <timeslot> HVHH C0/S1 C0/S1 C0/S2 +---- +<1> Legacy TCH/H0 is configured to use TSC 0 from set 1 (table 5.2.3a). +<2> V0(TCH/H1) is configured to use TSC 0 from set 1 (table 5.2.3a). +<3> V1(TCH/H1) is configured to use TSC 0 from set 2 (table 5.2.3b). + +NOTE: In the example for `HVHH`, legacy TCH/H0 does not belong to a _VAMOS pair_, +so it can be configured to use any Training Sequence Code without restrictions. + +[[trx_if_pdu_version_nego]] ==== TRXD header version negotiation -Messages on DATA interface may have different header formats, defined by a -version number, which can be negotiated on the control interface. By default, -the Transceiver will use the legacy header version (0). +Messages on DATA interface may have different formats, defined by a version number, +which can be negotiated on the control interface. By default, the Transceiver will +use the legacy header version (0). See <<trx_if_pdu_versioning>>. -The header format negotiation can be initiated by the BTS using 'SETFORMAT' -command. If the requested version is not supported by the transceiver, status -code of the response message should indicate a preferred (basically, the latest) +The format negotiation can be initiated by the BTS using `SETFORMAT` command. +If the requested version is not supported by the transceiver, status code of +the response message should indicate a preferred (basically, the latest) version. The format of this message is the following: ---- CMD SETFORMAT <ver_req> @@ -202,13 +362,53 @@ before `POWERON`, but can be also done afterwards. === TRXD protocol -Messages on the data interface carry one radio burst per UDP message. - -==== Uplink Data Burst - -Uplink data burst message structure differs from version 0 to 1. Basically, -version 1 contains an extended header with regards to version 0, and the final -padding existence is completely dropped. +Messages on the data interface carry one or optionally multiple radio bursts +(see <<trx_if_pdu_batching>>) per one UDP datagram. Two kinds of TRXD PDU exist: + +* `TRX -> L1` (from transceiver to the L1): Uplink messages received from the MS, +* `L1 -> TRX` (from the L1 to transceiver): Downlink messages sent to the MS. + +Depending on the origin and the version indicator, PDUs may have different structure. + +[[trx_if_pdu_versioning]] +==== PDU versioning + +The format of a PDU, i.e. presence and ordering of certain fields, is determined by +the version number indicated in the first octet. This is usually referred as +`TRXDvN`, where `N` is the version number (e.g. TRXDv0 or TRXDv1). A version number +indicates the message format to be used for both directions: `TRX -> L1` and +`L1 -> TRX`. The same version shall be used for all messages in both directions, +mixing in any way is not permitted. + +The version negotiation is optionally initiated by the `L1` on the control interface, +and expected to be performed before starting the transceiver (i.e. sending `POWERON` +command). See <<trx_if_pdu_version_nego>>. + +The current header allows to distinguish up to 16 different versions. +The following versions are defined so far: + +* TRXDv0 - initial version of TRXD protocol, inherited as-is from OpenBTS project. +* TRXDv1 (proposed in July 2019): +** Introduced the concept of protocol versioning; +** Introduced NOPE / IDLE indications; +** New field: MTS (Modulation and Training Sequence); +** New field: C/I (Carrier-to-interface) ratio; +** Downlink messages mostly unchanged. +* TRXDv2 (proposed in January 2021): +** Introduced the concept of burst batching (many bursts in one message); +** Changed the field ordering (facilitating aligned access); +** New field: batching indicator; +** New field: shadow indicator; +** New field: TRX number; +** New field: SCPIR for VAMOS. + +==== Uplink PDU format + +An Uplink TRXD PDU contains a demodulated burst with the associated measurements +(signal strength, timing delay, etc.) and TDMA frame/timeslot number. Starting +from TRXDv1, a PDU may contain no payload, indicating the upper layers that the +transceiver was not able to demodulate a burst (e.g. due to bad signal quality +or the lack of signal during IDLE TDMA frames). .TRXDv0 Uplink data burst message structure [packetdiag] @@ -218,13 +418,13 @@ padding existence is completely dropped. node_height = 40 0-3: VER(0) - 4: RES + 4: RFU 5-7: TN 8-39: FN 40-47: RSSI 48-63: TOA256 - 64-95: ...Payload... - 96-97: PAD + 64-95: Soft-bits + 96-111: PAD } ---- @@ -236,26 +436,95 @@ padding existence is completely dropped. node_height = 40 0-3: VER(1) - 4: RES + 4: RFU 5-7: TN 8-39: FN 40-47: RSSI 48-63: TOA256 64-71: MTS 72-87: C/I - 88-127: ...Payload... + 88-127: Soft-bits +} +---- + +.TRXDv1 NOPE / IDLE indication message structure +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0-3: VER(1) + 4: RFU + 5-7: TN + 8-39: FN + 40-47: RSSI + 48-63: TOA256 + 64-71: MTS (NOPE.ind) + 72-87: C/I +} +---- + +.TRXDv2 Uplink message structure +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0-3: VER(2) + 4: RFU + 5-7: TN + 8: BATCH + 9: RFU + 10-15: TRXN + 16-23: MTS + 24-31: RSSI + 32-47: TOA256 + 48-63: C/I + 64-95: FN + 96-127: Soft-bits +} +---- + +.TRXDv2 Uplink message structure (batched part) +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0-4: RFU + 5-7: TN + 8: BATCH + 9: SHADOW + 10-15: TRXN + 16-23: MTS + 24-31: RSSI + 32-47: TOA256 + 48-63: C/I + 64-95: Soft-bits } ---- VER: 4 bits:: -TRXD header version, v0 and v1 are specified so far. +TRXD header version, common for both `TRX -> L1` and `L1 -> TRX` directions. TN: 3 bits:: Timeslot number. -RES: 1 bit:: -Reserved, shall be 0. It can be used in the future to extend the TDMA TN range -to (0..15), in case anybody would need to transfer UMTS bursts. +RFU: variable bit-length:: +Reserved for Future Use. The sending side of the PDU shall set all bits to +{bit-zero}; the receiving side shall ignore `RFU` fields. + +BATCH: 1 bit:: +This bit indicates whether a batched PDU follows (see <<trx_if_pdu_batching>>). + +SHADOW: 1 bit:: +This bit indicates whether this is a _shadow PDU_ (see <<trx_if_pdu_vamos>>). + +TRXN: 6 bits:: +The transceiver (PHY channel) number this PDU is coming from. FN: 32 bits (4 bytes):: GSM frame number, big endian. @@ -276,7 +545,7 @@ value is computed from the training sequence of each burst, where the "ideal" training sequence is compared to the actual training sequence and the result expressed in centiBels. -Payload: 148 bytes for GSM, 444 bytes for EDGE:: +Soft-bits: 148 x N bytes (variable length, N defined by modulation type):: Contains the uplink burst. Unlike the downlink bursts, the uplink bursts are designated using the soft-bits notation, so the receiver can indicate its assurance from 0 to -127 that a given bit is 1, and from 0 to +127 that a given @@ -287,7 +556,7 @@ shift. This way: * 0 -> definite "0" * 255 -> definite "1". -PAD: 2 bits (optional):: +PAD: 2 bytes (optional):: Padding at the end, historical reasons (OpenBTS inheritance). Bits can take any value, but 0 is preferred. Only expected on TRXDv0 headers. @@ -300,22 +569,23 @@ is used in EDGE). .MTS field structure ---- -+-----------------+---------------------------------------+ -| 7 6 5 4 3 2 1 0 | bit numbers (value range) | -+-----------------+---------------------------------------+ -| X . . . . . . . | IDLE / nope 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) | ++-----------------+----------------------------------------+ ---- -IDLE / nope frame indication:: -The bit number 7 (MSB) is set to high when either nothing has been detected, or -during IDLE frames, so noise levels can be delivered, and avoid clock gaps on -the BTS side. Other bits are ignored, and should be set to low (`0`) in this -case. +NOPE / IDLE frame indication (referred to as NOPE.ind):: +The bit number 7 (MSB) shall be set to {bit-one} by the transceiver when either +nothing has been detected, so the BTS scheduler keeps processing bursts without +gaps, or during IDLE frames, so the current noise levels can be delivered. In +this case the remaining bits become meaningless and shall be set to {bit-zero}. +The payload (`Soft-bits` or `Hard-bits`) is omited. Modulation and TS set number:: GMSK has 4 sets of training sequences (see tables 5.2.3a-d), while 8-PSK (see @@ -324,30 +594,39 @@ also have several synchronization sequences. .Modulation and TS set number ---- -+-----------------+---------------------------------------+ -| 7 6 5 4 3 2 1 0 | bit numbers (value range) | -+-----------------+---------------------------------------+ -| . 0 0 X X . . . | GMSK, 4 TS sets (0..3) | -+-----------------+---------------------------------------+ -| . 0 1 0 X . . . | 8-PSK, 2 TS sets (0..1) | -+-----------------+---------------------------------------+ -| . 0 1 1 X . . . | AQPSK, 2 TS sets (0..1) | -+-----------------+---------------------------------------+ -| . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1) | -+-----------------+---------------------------------------+ -| . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1) | -+-----------------+---------------------------------------+ -| . 1 1 X X . . . | RESERVED (0) | -+-----------------+---------------------------------------+ ----- - -Training Sequence Code:: -The Training Sequence Code used to decode an Access or a Synchronization burst. -This field hence doesn't apply for Normal bursts. ++-----------------+---------------------------------------+--------------+ +| 7 6 5 4 3 2 1 0 | Description | Burst length | ++-----------------+---------------------------------------+--------------+ +| . 0 0 X X . . . | GMSK, 4 TS sets (0..3) | 148 x 1 | ++-----------------+---------------------------------------+--------------+ +| . 0 1 0 X . . . | 8-PSK, 2 TS sets (0..1) | 148 x 3 | ++-----------------+---------------------------------------+--------------+ +| . 0 1 1 0 . . . | GMSK, Access Burst (see note) | 148 x 1 | ++-----------------+---------------------------------------+--------------+ +| . 0 1 1 1 . . . | RFU (Reserved for Future Use) | ------- | ++-----------------+---------------------------------------+--------------+ +| . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1) | 148 x 4 | ++-----------------+---------------------------------------+--------------+ +| . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1) | 148 x 5 | ++-----------------+---------------------------------------+--------------+ +| . 1 1 X X . . . | AQPSK (Downlink), 4 TS sets (0..3) | 148 x 2 | ++-----------------+---------------------------------------+--------------+ +---- + +NOTE: A radio block on PDCH is carried by the sequence of four Normal Bursts. +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 / 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 -.TRXD Downlink data burst message structure +.TRXDv0 and TRXDv1 Downlink data burst message structure [packetdiag] ---- { @@ -355,31 +634,222 @@ This field hence doesn't apply for Normal bursts. node_height = 40 0-3: VER - 4: RES + 4: RFU 5-7: TN 8-39: FN 40-47: PWR - 48-95: ...Payload... + 48-95: Hard-bits +} +---- + +.TRXDv2 Downlink data burst message structure +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0-3: VER(2) + 4: RFU + 5-7: TN + 8: BATCH + 9: RFU + 10-15: TRXN + 16-23: MTS + 24-31: PWR + 32-39: SCPIR + 40-63: RFU + 64-95: FN + 96-127: Hard-bits +} +---- + +.TRXDv2 Downlink PDU structure (batched part) +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0-4: RFU + 5-7: TN + 8: BATCH + 9: RFU + 10-15: TRXN + 16-23: MTS + 24-31: PWR + 32-39: SCPIR + 40-63: RFU + 64-95: Hard-bits } ---- VER: 4 bits:: -TRXD header version, v0 and v1 are specified so far. +TRXD header version, common for both `TRX -> L1` and `L1 -> TRX` directions. TN: 3 bits:: Timeslot number. -RES: 1 bit:: -Reserved, shall be 0. It can be used in the future to extend the TDMA TN range -to (0..15), in case anybody would need to transfer UMTS bursts. +RFU: variable bit-length:: +Reserved for Future Use. The sending side of the PDU shall set all bits to +{bit-zero}; the receiving side shall ignore `RFU` fields. + +BATCH: 1 bit:: +This bit indicates whether a batched PDU follows (see <<trx_if_pdu_batching>>). + +TRXN: 6 bits:: +The transceiver (PHY channel) number this PDU is addressed to. + +MTS: 8 bits (1 byte):: +Contains the Modulation and Training Sequence information. See <<coding-mts>> +for more information on the encoding. FN: 32 bits (4 bytes):: GSM frame number, big endian. PWR: 8 bits (1 byte):: -Contains the relative (to the full-scale amplitude) transmit power level in dB. -The absolute value is set on the control interface. +Contains the relative (to the full-scale amplitude) transmit power *reduction* +in dB. The absolute value is set on the control interface, so the resulting +power is calculated as follows: `full_scale - (absolute_red + relative_red)`. -Payload: 148 bytes for GSM, 444 bytes for EDGE:: +SCPIR: 8 bits (1 byte):: +SCPIR (Subchannel Power Imbalance Ratio) - the ratio of power between Q and I +channels for a VAMOS pair. This field shall be present when `MTC` field +indicates the use of `AQPSK` modulation. Otherwise, all bits shall be set +to {bit-zero}. The value is a signed integer with a valid range: -10..10 dB. + +Hard-bits: 148 x N bytes (variable length, N defined by modulation type):: Contains the downlink burst. Each hard-bit (1 or 0) of the burst is represented using one byte (0x01 or 0x00 respectively). + +[[trx_if_pdu_batching]] +==== PDU batching + +Starting from TRXDv2, it's possible to combine several PDUs into a single +datagram - this is called _PDU batching_. The purpose of _PDU batching_ +is to reduce socket load and eliminate possible PDU reordering, especially +in a multi-TRX setup. + +All _batched PDUs_ in a datagram must belong to the same TDMA frame number +indicated in the first part. The ordering of PDUs in a datagram may be +different from the examples below, however it's recommended to batch PDUs +in ascending order determined by TDMA timeslot number and/or `TRXN`. + +The following PDU combinations in a datagram are possible: + +* `a)` one datagram contains PDUs with the same TDMA timeslot number for all +transceivers (total N PDUs per a TDMA timeslot); +* one datagram contains complete TDMA frame with PDUs for all 8 timeslots: +** `b)` either for a single transceiver (total 8 PDUs per a TDMA frame), +** `c)` or for all transceivers (total 8 x N PDUs per a TDMA frame). + +None of these combinations are mandatory to support. + +NOTE: Automatic negotiation of the batching algorithm(s) is not yet specified. +Currently both sides need to be manually configured to use _PDU batching_. + +NOTE: Size of the biggest possible TRXD datagram should be less than the +_MTU (Maximum Transmission Unit)_ of the network interface connecting +both BTS and the transceiver. Otherwise the datagram is split across +multiple IP packets, which may negatively affect performance. + +.Example: datagram structure for combination a) +---- ++--------+----------------+---------+------------------------+ +| TRXN=0 | TDMA FN=F TN=T | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=1 | TDMA FN=F TN=T | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=2 | TDMA FN=F TN=T | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=T | BATCH=0 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +---- + +.Example: datagram structure for combination b) +---- ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=0 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=1 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=2 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=7 | BATCH=0 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +---- + +.Example: datagram structure for combination c) +---- ++--------+----------------+---------+------------------------+ +| TRXN=0 | TDMA FN=F TN=0 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=0 | TDMA FN=F TN=1 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=0 | TDMA FN=F TN=2 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=6 | BATCH=1 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +| TRXN=N | TDMA FN=F TN=7 | BATCH=0 | Hard-/Soft-bits | ++--------+----------------+---------+------------------------+ +---- + +[[trx_if_pdu_vamos]] +==== Coding of VAMOS PDUs + +In VAMOS mode, the throughput of a cell is increased by multiplexing two subscribers +on a single TDMA timeslot. Basically, *two* bursts are getting transmitted during +one TDMA timeslot period, and both of them need delivered over the TRXD interface. + +In the Downlink direction, the two bursts belonging to a _VAMOS pair_ shall be +concatenated together and sent in one TRXD PDU. The resulting hard-bit sequence +shall *not* be interleaved: `V0(0..147) + V1(0..147)` (296 hard-bits total), i.e. +one complete burst for subscriber `V0` takes the first 148 bytes, and another +complete burst for subscriber `V1` takes the remaining 148 bytes. The `MTS` field +shall indicate the use of `AQPSK` modulation, and the `SCPIR` field shall indicate +the Power Imbalance Ratio between `V0` and `V1`. + +.Example: Downlink datagram containing a VAMOS PDU +---- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+-----------+---------------------------------------+ +| TRXN=N | TDMA FN=F TN=T | Mod=AQPSK | Hard-bits: V0(0..147) + V1(0..147) | ++--------+----------------+-----------+---------------------------------------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---- + +In the Uplink direction though, one or even both of the two bursts may be lost +(e.g. due to high noise figures), so they shall always be sent in two separate +PDUs. The missing bursts shall be substituted by NOPE indications, so it's +always a pair of _batched PDUs_. First PDU in a pair is called _primary PDU_, +the second is called _shadow PDU_. This is additionally indicated by the +`SHADOW` field, which is set to {bit-zero} and {bit-one}, respectively. The +`MTS` field shall indicate the use of `GMSK` modulation if the burst is present. + +.Example: Uplink datagram containing batched VAMOS PDUs (both present) +---- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+----------+----------+------------------------------+ +| TRXN=N | TDMA FN=F TN=T | SHADOW=0 | Mod=GMSK | Soft-bits for V0 (148 bytes) | ++--------+----------------+----------+----------+------------------------------+ +| TRXN=N | TDMA FN=F TN=T | SHADOW=1 | Mod=GMSK | Soft-bits for V1 (148 bytes) | ++--------+----------------+----------+----------+------------------------------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---- + +.Example: Uplink datagram containing batched VAMOS PDUs (one lost) +---- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++--------+----------------+----------+----------+------------------------------+ +| TRXN=N | TDMA FN=F TN=T | SHADOW=0 | Mod=GMSK | Soft-bits for V0 (148 bytes) | ++--------+----------------+----------+----------+------------------------------+ +| TRXN=N | TDMA FN=F TN=T | SHADOW=1 | NOPE.ind | ++--------+----------------+----------+----------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---- diff --git a/common/chapters/vty.adoc b/common/chapters/vty.adoc index dec3be2..70b2e48 100644 --- a/common/chapters/vty.adoc +++ b/common/chapters/vty.adoc @@ -57,6 +57,9 @@ following will explain the commonly used syntactical patterns: |=============== |Pattern|Example|Explanation |`A.B.C.D`|`127.0.0.1`|An IPv4 address +|`A.B.C.D/M`|`192.168.1.0/24`|An IPv4 address and mask +|`X:X::X:X`|`::1`|An IPv6 address +|`X:X::X:X/M`|`::1/128`|An IPv6 address and mask |`TEXT`|`example01`|A single string without any spaces, tabs |`.TEXT`|`Some information`|A line of text |`(OptionA\|OptionB\|OptionC)`|`OptionA`|A choice between a list of available options @@ -360,6 +363,7 @@ command with the parameter `vty-attributes` ---- OsmoBSC> show vty-attributes Global attributes: + ^ This command is hidden (check expert mode) ! This command applies immediately @ This command applies on VTY node exit Library specific attributes: @@ -402,14 +406,14 @@ OsmoBSC(config-net-bts)# list with-flags . ... write file [PATH] . ... write memory . ... write - . ... show running-config + . ... show running-config <1> . ... exit . ... end - . o.. type (unknown|bs11|nanobts|rbs2000|nokia_site|sysmobts) + . o.. type (unknown|bs11|nanobts|rbs2000|nokia_site|sysmobts) <2> . ... description .TEXT . ... no description . o.. band BAND - . .r. cell_identity <0-65535> + . .r. cell_identity <0-65535> <3> . .r. dtx uplink [force] . .r. dtx downlink . .r. no dtx uplink @@ -419,9 +423,13 @@ OsmoBSC(config-net-bts)# list with-flags . o.. ipa unit-id <0-65534> <0-255> . o.. ipa rsl-ip A.B.C.D . o.. nokia_site skip-reset (0|1) - ! ... nokia_site no-local-rel-conf (0|1) - ! ... nokia_site bts-reset-timer <15-100> + ! ... nokia_site no-local-rel-conf (0|1) <4> + ! ... nokia_site bts-reset-timer <15-100> <4> ---- +<1> This command has no attributes assigned. +<2> This command applies on A-bis OML link (re)establishment. +<3> This command applies on A-bis RSL link (re)establishment. +<4> This command applies immediately. There are multiple columns because a single command may be associated with multiple attributes at the same time. To improve readability each flag letter @@ -432,3 +440,39 @@ flags at all. Those commands either play an exceptional role (interactive commands outside "configure terminal", vty node navigation commands, commands to show / write the config file) or will require a full restart of the overall process to take effect. + +==== The expert mode + +Some VTY commands are considered relatively dangerous if used in production operation, +so the general approach is to hide them. This means that they don't show up anywhere +but the source code, but can still be executed. On the one hand, this approach reduces +the risk of an accidental invocation and potential service degradation; on the other, +it complicates intentional use of the hidden commands. + +The VTY features so-called __expert__ mode, that makes the hidden commands appear in +the interactive help, as well as in the XML VTY reference, just like normal ones. This +mode can be activated from the 'VIEW' node by invoking the `enable` command with the +parameter `expert-mode`. It remains active for the individual VTY session, and gets +disabled automatically when the user switches back to the 'VIEW' node or terminates +the session. + +A special attribute in the output of the `list with-flags` command indicates whether +a given command is hidden in normal mode, or is a regular command: + +.Example: Hidden commands in the output of the `list with-flags` command +---- +OsmoBSC> enable expert-mode <1> +OsmoBSC# list with-flags + ... + ^ bts <0-255> (activate-all-lchan|deactivate-all-lchan) <2> + ^ bts <0-255> trx <0-255> (activate-all-lchan|deactivate-all-lchan) <2> + . bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> mdcx A.B.C.D <0-65535> <3> + ^ bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> (borken|unused) <2> + . bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> handover <0-255> <3> + . bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> assignment <3> + . bts <0-255> smscb-command (normal|schedule|default) <1-4> HEXSTRING <3> + ... +---- +<1> This command enables the __expert__ mode. +<2> This is a hidden command (only shown in the __expert__ mode). +<3> This is a regular command that is always shown regardless of the mode. diff --git a/common/images/gb-concepts-pool.pdf b/common/images/gb-concepts-pool.pdf Binary files differnew file mode 100644 index 0000000..d95f191 --- /dev/null +++ b/common/images/gb-concepts-pool.pdf diff --git a/common/images/gb-ip-nsvc.pdf b/common/images/gb-ip-nsvc.pdf Binary files differnew file mode 100644 index 0000000..32a0442 --- /dev/null +++ b/common/images/gb-ip-nsvc.pdf 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 852d8e2..bcd956b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,208 @@ +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 ] + * bibliography: Add more user manuals + * bibliography: https everywhere. + * cs7-config: Describe special meaning of M3UA routing context '0' + + [ Vadim Yanitskiy ] + * glossary.adoc: add brief definitions of AQPSK and VAMOS + * TRXC: use monospace formatting (the backticks) for 'SETFORMAT' + * TRXC: add missing description of the 'SETTSC' command + * TRXC: add proposal for multiple Training Sequences + * TRXC: introduce VAMOS enabled channel combinations + * TRXD: fix optional padding length: bits vs bytes + * TRXD: cosmetic: clarify soft-/hard-bits on packet diagrams + * TRXD: clarify the meaning of field 'PWR' in Downlink messages + * TRXD: use different coding for AQPSK in the 'MTC' field + * TRXD: reserve a combination for Access Bursts on PACCH + * TRXD: rework description of the 'Training Sequence Code' field + * TRXD: clarify description of NOPE / IDLE indications + * TRXD: more information on PDU versioning and some highlights + * logging: add documentation for 'systemd-journal' target + + -- Pau Espin Pedrol <pespin@sysmocom.de> Tue, 23 Feb 2021 12:59:20 +0100 + +osmo-gsm-manuals-dev (1.0.0) unstable; urgency=medium + + [ Daniel Willmann ] + * bts: Document access control classes and acc ramping + * bts.adoc: Add information about RACH tuning parameters + + [ Neels Hofmeyr ] + * fix srcdir to reflect $abs_srcdir + * fixup: ensure existence of $(abs_srcdir) + * add common/chapters/cs7-config + * vty reference: allow reference XML generated at build time + * bibliography, glossary: add MSC pooling related bits + + [ Harald Welte ] + * port_numbers: Add osmo-mgw CTRL port + * port_numbers: Add missing mDNS port for D-GSM / osmo-hlr + * synchronize port_numbers.adoc with wiki + * port_numbers: Add port numbers for upcoming OsmoSMLC + * biblio: Add 3GPP TS 31.103 (ISIM) + * sigtran: Mention that M3UA was chosen by 3GPP + * sigtran: Describe sctp/m3ua role, multi-homing, traffic-modes + * cs7-config: Mention OsmoSMLC + * cs7-config: Explain that A/Iu/Lb interfaces are reouted via STP + * cs7-config: Reference the OsmoSTP user manual for more info on SS7 + * Add common chapters on GB interface variants and SGSN pool + + [ Vadim Yanitskiy ] + * logging: fix section 6.5.3: logging level s/all/force-all/ fatal + * port_numbers: fix: GSMTAP has noting to do with port 2427/udp + * GSUP: fix E-Routing-Error: both session state / ID IEs are optional + * vty_reference.xsl: handle application specific attributes + * vty_reference.xsl: also handle 'global' and 'library' attributes + * chapters/vty: add IPv4/mask and IPv6/mask examples + * chapters/vty: add documentation for the expert mode + * chapters/vty: add in-place comments to the attribute examples + * Makefile.docbook.inc: fix incorrect variable name in documentation + * Makefile.vty-reference.inc: create 'generated' in this file + * Makefile.docbook.inc: allow to re-define the include directory + * vty_reference_combine.sh: print the final result to stdout + * Makefile.docbook.inc: generate *.pdf in the given directory + * Makefile.common.inc: make 'publish' target use $(UPLOAD_FILES) + + [ Pau Espin Pedrol ] + * trx_if: Clarify {SET;ADJ}POWER TRXC commands + * trx_if.adoc: Document cmd NOMTXPOWER + * Drop common/chapters/{bts,bsc}.adoc + * chapters: Introduce vty_cpu_sched.adoc chapter + * trx_if.adoc: Document RFMUTE TRXC command + + [ Philipp Maier ] + * vty: explain how command attributes are used + + -- Harald Welte <laforge@osmocom.org> Wed, 06 Jan 2021 17:21:50 +0100 + osmo-gsm-manuals-dev (0.3.0) unstable; urgency=medium [ Oliver Smith ] 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/debian/patches/build-for-debian8.patch b/debian/patches/build-for-debian8.patch deleted file mode 100644 index 58f49c3..0000000 --- a/debian/patches/build-for-debian8.patch +++ /dev/null @@ -1,18 +0,0 @@ ---- a/debian/control -+++ b/debian/control -@@ -7,7 +7,6 @@ Build-Depends: autotools-dev, - pkg-config, - # All below also need to be in Depends - asciidoc, -- asciidoc-dblatex, - dblatex, - docbook5-xml, - graphviz, -@@ -23,7 +22,6 @@ Package: osmo-gsm-manuals-dev - Architecture: all - Depends: ${misc:Depends}, - asciidoc, -- asciidoc-dblatex, - dblatex, - docbook5-xml, - graphviz, diff --git a/tests/Makefile.am b/tests/Makefile.am index 641b35c..0761d48 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST = test-usermanual-docinfo.xml \ vty \ test2-vty-reference.xml \ vty-test2 \ + chapters \ $(NULL) # Do not install any of the test pdfs @@ -12,7 +13,9 @@ OSMO_GSM_MANUALS_NO_INSTALL = 1 # Generate adoc file that includes all chapters (OS#4183: glossary.adoc must be the last file) ASCIIDOC = test-usermanual.adoc ASCIIDOC_DEPS = -COMMON_CHAPTERS = $(shell find $(OSMO_GSM_MANUALS_DIR)/common/chapters -name '*.adoc' | grep -v glossary\.adoc) \ +COMMON_CHAPTERS = $(shell find $(OSMO_GSM_MANUALS_DIR)/common/chapters -name '*.adoc' \ + ! -name glossary.adoc \ + ! -name mgcp_extension_osmux.adoc) \ $(OSMO_GSM_MANUALS_DIR)/common/chapters/glossary.adoc $(ASCIIDOC): $(COMMON_CHAPTERS) echo ":gfdl-enabled:" > $@ @@ -31,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 diff --git a/tests/chapters/qos-example.adoc b/tests/chapters/qos-example.adoc new file mode 100644 index 0000000..d398243 --- /dev/null +++ b/tests/chapters/qos-example.adoc @@ -0,0 +1,3 @@ +=== QoS example for example manual + +Quite exemplary. |