summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--build/Makefile.common.inc6
-rw-r--r--build/Makefile.docbook.inc9
-rw-r--r--build/Makefile.vty-reference.inc29
-rwxr-xr-xbuild/vty_reference_combine.sh32
-rw-r--r--common/chapters/cs7-config.adoc16
-rw-r--r--common/chapters/gb-ip-sns.msc38
-rw-r--r--common/chapters/gb-pool.adoc62
-rw-r--r--common/chapters/gb-variants.adoc179
-rw-r--r--common/chapters/sigtran.adoc65
-rw-r--r--common/chapters/vty.adoc54
-rw-r--r--common/images/gb-concepts-pool.pdfbin0 -> 42867 bytes
-rw-r--r--common/images/gb-ip-nsvc.pdfbin0 -> 67486 bytes
-rw-r--r--debian/changelog54
13 files changed, 504 insertions, 40 deletions
diff --git a/build/Makefile.common.inc b/build/Makefile.common.inc
index b98e83f..ca06962 100644
--- a/build/Makefile.common.inc
+++ b/build/Makefile.common.inc
@@ -27,10 +27,8 @@ clean:
distclean: clean
-publish: all
- mkdir -p out
- cp *.pdf out
- rsync -avz -e "$(SSH_COMMAND)" ./out/ docs@rita.osmocom.org:web-files/latest/
+publish: $(UPLOAD_FILES)
+ rsync -avz -e "$(SSH_COMMAND)" $(UPLOAD_FILES) docs@rita.osmocom.org:web-files/latest/
# Install and uninstall targets
# Notes about OSMO_GSM_MANUALS_NO_INSTALL:
diff --git a/build/Makefile.docbook.inc b/build/Makefile.docbook.inc
index 373db7d..eb0ee25 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,6 +27,9 @@ UPLOAD_FILES += $(DOCBOOKS_PDF)
all: $(DOCBOOKS_PDF)
+# Allow the users to re-define the include directory
+INC_DIR ?= $(PWD)/generated
+
# Lint the file
%.xml-lint: %.xml
xmllint --xinclude --postvalid --noout $<
@@ -34,6 +37,6 @@ all: $(DOCBOOKS_PDF)
# 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 $@) $<
+ dblatex --xslt-opts="--path $(realpath $(OSMO_GSM_MANUALS_DIR))/common/chapters:$(INC_DIR)" \
+ $(dblatex_quiet) -P draft.mode=no -o $@ $<
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/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/common/chapters/cs7-config.adoc b/common/chapters/cs7-config.adoc
index c489883..a0957fd 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,
@@ -57,6 +61,18 @@ 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
+
+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.
+
+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
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-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/gb-variants.adoc b/common/chapters/gb-variants.adoc
new file mode 100644
index 0000000..dc978f6
--- /dev/null
+++ b/common/chapters/gb-variants.adoc
@@ -0,0 +1,179 @@
+[[gb_variants]]
+== Gb interface variants
+
+There are a couple of variants of the Gb interface out there. This
+section tries to provide an overview into what those variants are, how
+they differ from each other and how to configure Osmocom software
+accordingly.
+
+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.
+
+=== 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.
+
+.Example: Gb over Frame Relay configuration
+----
+ns
+ nse 2001 nsvci 11 frnet hdlcnet1 dlci 16 <1>
+ nse 2001 nsvci 12 frnet hdlcnet2 dlci 17
+ nse 2001 nsvci 13 frnet hdlcnet3 dlci 18
+ nse 2001 nsvci 14 frnet hdlcnet4 dlci 19
+ nse 2002 nsvci 15 frnet hdlcnet5 dlci 20 <2>
+ nse 2002 nsvci 16 frnet hdlcnet6 dlci 21
+ nse 2003 nsvci 17 frnet hdlcnet7 dlci 22 <3>
+ nse 2003 nsvci 18 frnet hdlcnet8 dlci 23
+----
+<1> one NSE (2001) with four NS-VCI (11..14) on hdlcnet1..4 with their respective DLCI
+<2> another NSE (2002) with two NS-VCI (15..16) on hdlcnet5..6 with their respective DLCI
+<3> another NSE (2003) with two NS-VCI (17..18) on hdlcnet7..8 with their respective DLCI
+
+==== FR Driver Support
+
+The Osmocom NS/FR support 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. You must hence use
+`sethdlc hdlcX fr lmi none` to configure the HDLC net-devices for use
+with Osmocom. The net-devices must also be _up_, e.g. using the
+`ip link set hdlcX up` command in some system start-up script.
+
+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 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.
+
+Those GRE/IP messages from the external Cisco router are then passed to
+the Osmocom Gb stack (e.g. to `osmo-gbproxy`).
+
+The protocol stacking is BSSGP/NS/FR/GRE/IP.
+
+FIXME: Example configuration
+
+----
+ns
+ encapsulation framerelay-gre enabled 1
+ encapsulation framerelay-gre local-ip 127.0.0.1
+----
+
+
+=== 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.
+
+FIXME: Full example configuration
+
+----
+ns
+ encapsulation udp local-ip 127.0.0.1
+ encapsulation udp local-port 23000
+----
+
+[[gb-ip-sns]]
+=== 3GPP Gb over IP with IP-SNS
+
+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) in order to dynamically
+exchange information about IP endpoints (IP+port tuples) between the Gb
+interface peers. This means that normally only one basic / first IP
+endpoint needs to be configured. All additional IP endpoints and their
+relative weight for load distribution are then negotiated via the
+IP-SNS.
+
+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 PCU-side 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[]
+----
+
+==== PCU Configuration
+
+FIXME: Full example configuration
+
+.Example: osmo-pcu configuration for use with IP-SNS
+----
+pcu
+ gb-dialect ip-sns
+----
+
+NOTE: The initial IP endpoint for osmo-pcu is not configured in the PCU
+itself, but in the BSC, who downloads the Gb interface configuration to
+the BTS during BTS OML start-up, which in turn passes it to the PCU over
+the unix domain socket between BTS and PCU
diff --git a/common/chapters/sigtran.adoc b/common/chapters/sigtran.adoc
index 9e02f38..cbf513e 100644
--- a/common/chapters/sigtran.adoc
+++ b/common/chapters/sigtran.adoc
@@ -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,65 @@ 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 SIGTARN
+
+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 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/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
new file mode 100644
index 0000000..d95f191
--- /dev/null
+++ b/common/images/gb-concepts-pool.pdf
Binary files differ
diff --git a/common/images/gb-ip-nsvc.pdf b/common/images/gb-ip-nsvc.pdf
new file mode 100644
index 0000000..32a0442
--- /dev/null
+++ b/common/images/gb-ip-nsvc.pdf
Binary files differ
diff --git a/debian/changelog b/debian/changelog
index 852d8e2..d999a89 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,57 @@
+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 ]