From ed4f7f278342257c27074429aa58c19081da6450 Mon Sep 17 00:00:00 2001 From: Alexander Couzens Date: Tue, 16 Mar 2021 17:38:00 +0100 Subject: common/chapters: extend gb/ns2 chapters Merge gb-variants.adoc into gb-ns2.adoc Add a general overview of the internal structure which is also used by the vty. Move the configuration into a seperate adoc to allow the PCU manual to skip the part which doesn't apply for it. Copy the timer configuration into gb.adoc to allow document newer timers. All users of the NS2 code will use the timer sub-chapter. Related: OS#5077 Change-Id: I902b850528cbc04bd469590babd84cccf64300e8 --- common/chapters/gb-ns2-configuration-timer.adoc | 36 +++++ common/chapters/gb-ns2-configuration.adoc | 172 ++++++++++++++++++++++ common/chapters/gb-ns2.adoc | 186 ++++++++++++++++++++++++ common/chapters/gb-variants.adoc | 179 ----------------------- 4 files changed, 394 insertions(+), 179 deletions(-) create mode 100644 common/chapters/gb-ns2-configuration-timer.adoc create mode 100644 common/chapters/gb-ns2-configuration.adoc create mode 100644 common/chapters/gb-ns2.adoc delete mode 100644 common/chapters/gb-variants.adoc diff --git a/common/chapters/gb-ns2-configuration-timer.adoc b/common/chapters/gb-ns2-configuration-timer.adoc new file mode 100644 index 0000000..ab8585f --- /dev/null +++ b/common/chapters/gb-ns2-configuration-timer.adoc @@ -0,0 +1,36 @@ +==== Gb/NS Timer configuration + +The NS protocol features a number of configurable timers. + +.List of configurable NS timers +|=== +|tns-block|(un)blocking timer timeout (secs) +|tns-block-retries|(un)blocking timer; number of retries +|tns-reset|reset timer timeout (secs) +|tns-reset-retries|reset timer; number of retries +|tns-test|test timer timeout (secs) +|tns-alive|alive timer timeout (secs) +|tns-alive-retries|alive timer; number of retries +|tsns-prov|SNS provision timeout (secs) used by all SNS auto configuration procedures. +|tsns-size-retries|SNS Size procedure; number of retries +|tsns-config-retries|SNS Config procedure; number of retries +|=== + +All timer can be configured by vty configuration + +.Example of timeouts +---- +ns + timer tns-block 3 + timer tns-block-retries 3 + timer tns-reset 3 + timer tns-reset-retries 3 + timer tns-test 30 + timer tns-alive 3 + timer tns-alive-retries 10 + timer tsns-prov 10 + timer tsns-size-retries 3 + timer tsns-config-retries 3 +---- + +// FIXME: ladder diagrams for every timer diff --git a/common/chapters/gb-ns2-configuration.adoc b/common/chapters/gb-ns2-configuration.adoc new file mode 100644 index 0000000..b8f2b03 --- /dev/null +++ b/common/chapters/gb-ns2-configuration.adoc @@ -0,0 +1,172 @@ +=== Gb/NS configuration + +This section describes the configuration that libosmogb exposes via the +VTY and is valid for OsmoSGSN and OsmoGbProxy. + +==== Gb over Frame Relay over E1/T1 + +The Gb over Frame Relay over E1/T1 requires: + +* a hdlc interface +* a frame relay role (fr or frnet) +* the DLCI + +.Example: Gb over Frame Relay configuration #1 +---- +ns + bind fr sitea1 <1> + fr hdlc1 frnet <2> + nse 2001 <3> + nsvci fr sitea1 dlci 16 nsvci 11 +---- +<1> a Gb-over-FR bind with the name sitea1 +<2> connect the hdlc1 device with the role frnet to sitea1 +<3> one NSE (2001) with a single NS-VCI 11 on sitea1 with DLCI 16 + +.Example: Gb over Frame Relay configuration #2 +---- +ns + bind fr sitea1 <1> + fr hdlc1 frnet <2> + bind fr sitea2 + fr hdlc2 frnet + bind fr sitea3 + fr hdlc3 frnet + bind fr sitea4 + fr hdlc4 frnet + bind fr siteb1 + fr hdlc5 frnet + bind fr siteb2 + fr hdlc6 frnet + bind fr sitec1 + fr hdlc7 frnet + bind fr sitec2 + fr hdlc8 frnet + nse 2001 <3> + nsvci fr sitea1 dlci 16 nsvci 11 + nsvci fr sitea2 dlci 17 nsvci 12 + nsvci fr sitea3 dlci 18 nsvci 13 + nsvci fr sitea4 dlci 19 nsvci 14 + nse 2002 <4> + nsvci fr siteb5 dlci 20 nsvci 15 + nsvci fr siteb6 dlci 21 nsvci 16 + nse 2003 <5> + nsvc fr sitec7 dlci 22 nsvci 17 + nsvc fr sitec8 dlci 23 nsvci 18 +---- +<1> a Gb-over-FR bind with the name sitea1 +<2> connect the hdlc1 device with the role frnet to sitea1 +<3> one NSE (2001) with four NS-VCI (11..14) on sitea1..4 with their respective DLCI +<4> another NSE (2002) with two NS-VCI (15..16) on siteb1..2 with their respective DLCI +<5> another NSE (2003) with two NS-VCI (17..18) on sitec1..2 with their respective DLCI + + +==== Gb over IP "ip.access style" + +The Gb over IP "ip.access style" can be used with a dynamic configuration or with a +static configuration + +The static configuration requires to configure all endpoints on the BSS and SGSN. +In constrast the dynamic configuration allows the SGSN to have only a reduced configuration. + +===== Gb over IP "ip.access style" dynamic configuration + +.Example: Gb over IP/UDP ip.access style dynamic configuration (SGSN) +---- +ns + bind udp ran1 <1> + listen 10.100.1.1 23000 <2> + accept-ipaccess <3> +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.1.1:23000 +<3> accept unknown BSS of ip.access style + +.Example: Gb over IP/UDP "ip.access style" dynamic configuration (GbProxy as BSS) +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.1.1:23000 +<3> accept unknown BSS of ip.access style + +NOTE: The OsmoPCU supports ip.access style Gb/NS but doesn't support this vty configuration because +it's receiving the configuration from the BTS/BSC. + +===== Gb over IP "ip.access style" static configuration + +.Example: Gb over IP/UDP "ip.access style" dynamic configuration (SGSN) +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 + +.Example: Gb over IP/UDP "ip.access style" dynamic configuration (GbProxy as BSS) +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc ipa ran1 10.100.1.1 23000 nsvci 1001 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> NSE 1001 with nsvc 1001 as ip.access style + +NOTE: The OsmoPCU supports "ip.access style" Gb/NS but doesn't support this vty configuration because +it's receiving the configuration from the BTS/BSC. + + +==== Gb over IP 3GPP static configuration + +A static IP/UDP configuration without SNS as specified by 3GPP 48.016. + +.Example: Gb over IP/UDP static configuration BSS/SGSN +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + nse 1001 <3> + nsvc udp ran1 10.100.1.1 23000 signalling-weight 2 data-weight 2 + nsvc udp ran1 10.100.1.2 23000 <4> +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> add NSE 1001 with 2 NSVC +<4> short configuration with default signalling and data weight of 1 + +==== Gb over IP 3GPP auto configuration as BSS + +IP/UDP auto-configuration with initial endpoints to an SGSN. +The auto-configuration will use the first bind to connect to the +first endpoint. If this fails Osmocom will iterate over all endpoints and binds to find +a working combination. + +.Example: Gb over IP/UDP auto-configuration as BSS +---- +ns + bind udp ran1 <1> + listen 10.100.0.1 23000 <2> + bind udp ran2 + listen 10.100.0.2 23000 + bind udp ran3 + listen 10.100.0.3 23000 + nse 1001 <3> + ip-sns-bind ran1 <4> + ip-sns-bind ran2 + ip-sns-endpoint 10.100.1.1 <5> + ip-sns-endpoint 10.100.1.2 +---- +<1> create a IP/UDP bind with name ran1 +<2> bind to 10.100.0.1:23000 +<3> add NSE 1001 with 2 initial SNS endpoints +<4> add ran1 to the list of available endpoints +<5> add 10.100.1.1 as initial endpoint + diff --git a/common/chapters/gb-ns2.adoc b/common/chapters/gb-ns2.adoc new file mode 100644 index 0000000..38f7c4f --- /dev/null +++ b/common/chapters/gb-ns2.adoc @@ -0,0 +1,186 @@ +== 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 configres +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. + +<> 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 <>. 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. + + +=== VTY + +This section describes the VTY commands to inspect or interact with the NS. + diff --git a/common/chapters/gb-variants.adoc b/common/chapters/gb-variants.adoc deleted file mode 100644 index dc978f6..0000000 --- a/common/chapters/gb-variants.adoc +++ /dev/null @@ -1,179 +0,0 @@ -[[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. - -<> 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 <>. 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 -- cgit v1.2.3