initial checkin of manuals to public repo
The manuals existed in different form for several years in an internal
sysmocom repository. However, since they had just recently been
converted from docboox-xml to asciidoc and all files have been
re-shuffled for enabling the public release, there's not much point in
keeping the history with git-filter-branch.
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
new file mode 100644
index 0000000..ce726ea
--- /dev/null
+++ b/doc/manuals/chapters/configuration.adoc
@@ -0,0 +1,163 @@
+== Configuring OsmoSGSN
+
+Contrary to other network elements (like OsmoBSC, OsmoNITB), the
+OsmoSGSN has a relatively simple configuration.
+
+On the one hand, this is primary because the PCU configuration happens
+from the BSC side.
+
+On the other hand, it is because the Gb interface does not need an
+explicit configuration of all each PCU connecting to the SGSN. The
+administrator only has to ensure that the NS and BSSGP layer identities
+(NSEI, NSVCI, BVCI) are unique for each PCU connecting to the SGSN.
+
+=== Configuring the Gp interface
+
+The Gp interface is the GTP-C and GTP-U based interface between the SGSN
+and the GGSNs. It is implemented via UDP on well-known source and
+destination ports.
+
+When a MS requests establishment of a PDP context, it specifies the APN
+(Access Point Name) to which the context shall be established. This APN
+determines which GGSN shall be used, and that in turn determines which
+external IP network the MS will be connected to.
+
+There are two modes in which GGSNs can be configured:
+
+. static GGSN/APN configuration
+. dynamic GGSN/APN configuration
+
+==== Static GGSN/APN configuration
+
+In this mode, there is a static list of GGSNs and APNs configured in
+OsmoSGSN via the VTY / config file.
+
+This is a non-standard method outside of the 3GPP specifications for the
+SGSN, and is typically only used in private/small GPRS networks without
+any access to a GRX.
+
+.Example: Static GGSN/APN configuration (single catch-all GGSN)
+----
+OsmoSGSN(config-sgsn)# gtp local-ip 172.0.0.1 <1>
+OsmoSGSN(config-sgsn)# ggsn 0 remote-ip 127.0.0.2 <2>
+OsmoSGSN(config-sgsn)# ggsn 0 gtp-version 1 <3>
+OsmoSGSN(config-sgsn)# apn * ggsn 0 <4>
+----
+<1> Configure the local IP address at the SGSN used for Gp/GTP
+<2> Specify the remote IP address of the GGSN (for GGSN 0)
+<3> Specify the GTP protocol version used for GGSN 0
+<4> Route all APN names to GGSN 0
+
+
+==== Dynamic GGSN/APN configuration
+
+In this mode, the SGSN will use a DNS-based method to perform the lookup
+from the APN (as specified by the MS) towards the GGSN IP address.
+
+This is the official method as per the 3GPP specifications for the SGSN,
+and what is used on GRX.
+
+.Example: Dynamic GGSN/APN configuration
+----
+OsmoSGSN(config-sgsn)# gtp local-ip 192.168.0.11 <1>
+OsmoSGSN(config-sgsn)# ggsn dynamic <2>
+OsmoSGSN(config-sgsn)# grx-dns-add 1.2.3.4 <3>
+----
+<1> Configure the local IP address at the SGSN used for Gp/GTP
+<2> Enable the dynamic GGSN resolving mode
+<3> Specify the IP address of a DNS server for APN resolution
+
+
+=== Subscriber Configuration
+
+As opposed to OsmoNITB, OsmoSGSN does not feature a built-in HLR.
+
+It can thus operate only in the following two modes:
+
+. Accessing an external HLR (or HLR gateway) via the GSUP protocol
+. Accepting subscribers based on internal ACL (access control list)
+
+==== Accessing an external HLR via GSUP
+
+The non-standard GSUP protocol was created to provide OsmoSGSN with
+access to an external HLR while avoiding the complexities of the
+TCAP/MAP protocol stack commonly used by HLRs.
+
+A custom HLR could either directly implement GSUP, or an external gateway
+can be used to convert GSUP to the respective MAP operations.
+
+The primitives/operations of GSUP are modelled to have a 1:1
+correspondence to their MAP counterparts. However, the encoding is much
+simplified by use of a binary TLV encoding similar to Layer 3 of
+GSM/GPRS.
+
+GSUP performs a challenge-response authentication protocol called OAP,
+which uses the standard MILEAGE algorithm for mutual authentication
+between OsmoSGSN and the HLR/HLR-GW.
+
+[[sgsn-ex-gsup]]
+.Example: Using an external HLR via GSUP
+----
+OsmoSGSN(config-sgsn)# gsup remote-ip 2.3.4.5 <1>
+OsmoSGSN(config-sgsn)# gsup remote-port 10000 <2>
+OsmoSGSN(config-sgsn)# gsup oap-k 000102030405060708090a0b0c0d0e0f <3>
+OsmoSGSN(config-sgsn)# gsup oap-opc 101112131415161718191a1b1c1d1e1f <4>
+----
+<1> Configure the IP address of the (remote) HLR or HLR-GW
+<2> Configure the TCP port of the (remote) HLR or HLR-GW
+<3> Specify the OAP shared key
+<4> Specify the OAP shared OPC
+
+
+=== CDR configuration
+
+OsmoSGSN can write a text log file containing CDR (call data records),
+which are commonly used for accounting/billing purpose.
+
+.Example: CDR configuration
+----
+OsmoSGSN(config-sgsn)# cdr filename /var/log/osmosgsn.cdr
+OsmoSGSN(config-sgsn)# cdr interval 600 <1>
+----
+<1> Periodically log existing PDP contexts every 600 seconds (10 min)
+
+The CDR file is a simple CSV file including a header line naming the
+individual fields of each CSV line.
+
+[[sgsn-cdr]]
+.Descripton of CSV fields in OsmoSGSN CDR file
+[options="header",cols="15%,85%"]
+|===
+|timestamp|Timestamp in YYYYMMDDhhmmssXXX where XXX are milli-seconds
+|imsi|IMSI causing this CDR
+|imei|IMEI causing this CDR
+|msisdn|MSISDN causing this CDR (if known)
+|cell_id|Cell ID in which the MS was registered last
+|lac|Location Area Code in which the MS was registered last
+|hlr|HLR of the subscriber
+|event|Possible events are explained below in <<sgsn-cdr-evt>>
+|pdp|
+|pdp_duration|duration of the PDP context so far
+|ggsn_addr|GGSN related to the PDP context
+|sgsn_addr|SGSN related to the PDP context
+|apni|APN identifier of the PDP context
+|eua_addr|IP address allocated to the PDP context
+|vol_in|Number of bytes in MO direction
+|vol_out|Number of bytes in MT direction
+|charging_id|Related charging ID
+|===
+
+[[sgsn-cdr-event]]
+.Description of OsmoSGSN CDR Events
+[options="header",cols="15%,85%"]
+|===
+|Event|Description
+|attach|GMM ATTACH COMPLETE about to be sent to MS
+|update|GMM ROUTING AREA UPDATE COMPLETE about to be sent to MS
+|detach|GMM DETACH REQUEST received from MS
+|free|Release of the MM context memory
+|pdp-act|GTP CREATE PDP CONTEXT CONFIRM received from GGSN
+|pdp-deact|GTP DELETE PDP CONTEXT CONFIRM received from GGSN
+|pdp-terminate|Forced PDP context termination during MM context release
+|pdp-free|Release of the PDP context memory
+|===
diff --git a/doc/manuals/chapters/gsup.adoc b/doc/manuals/chapters/gsup.adoc
new file mode 100644
index 0000000..9efc8c0
--- /dev/null
+++ b/doc/manuals/chapters/gsup.adoc
@@ -0,0 +1,592 @@
+[[gsup]]
+== GPRS Subscriber Update Protocol
+
+=== General
+
+This chapter describes the remote protocol that is used by the SGSN to update
+and manage the local subscriber list. The protocol and the messages are
+designed after the corresponding MAP messages (see 3GPP TS 09.02) with the
+following differences:
+
+* The encoding uses TLV structures instead of ASN.1 encodings
+* Segmentation is not used
+
+For more information, see the specification of the Gr interface (3GPP TS 03.60).
+
+=== Connection
+
+The protocol expects that a reliable, ordered, packet boundaries preserving
+connection is used (e.g. IPA over TCP). The remote peer is either a service
+that understands the protocol natively or a wrapper service that maps the
+messages to/from real MAP messages that can be used to directly communicate
+with an HLR.
+
+=== Using IPA
+
+By default, the following identifiers should be used:
+
+* IPA Stream ID: 0xEE (OSMO)
+* IPA OSMO protocol extension: 0x05
+
+For more information about the IPA multiplex, please see the 'OsmoBTS
+Abis/IP Specifiation'.
+
+=== Procedures
+
+==== Authentication management
+
+The SGSN sends a SEND_AUTHENTICATION_INFO_REQ message containing the MS's IMSI
+to the peer. On errors, especially if authentication info is not availabe for
+that IMSI, the peer returns a SEND_AUTHENTICATION_INFO_ERR message. Otherwise
+the peer returns a SEND_AUTHENTICATION_INFO_RES message. If this message
+contains at least one authentication tuple, the SGSN replaces all tuples that
+are assigned to the subscriber. If the message doesn't contain any tuple the
+SGSN may reject the Attach Request. (see 3GPP TS 09.02, 25.5.6)
+
+==== Location Updating
+
+The SGSN sends a UPDATE_LOCATION_REQ to the peer. If the request is denied by
+the network, the peer returns an UPDATE_LOCATION_ERR message to the SGSN.
+Otherwise the peer returns an UPDATE_LOCATION_RES message containing all
+information fields that shall be inserted into the subscriber record. If
+the 'PDP info complete' information element is set in the message, the SGSN
+clears existing PDP information fields in the subscriber record first.
+(see 3GPP TS 09.02, 19.1.1.8)
+
+...
+
+=== Message Format
+
+==== General
+
+Every message is based on the following message format
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+If a numeric range is indicated in the 'presence' column, multiple information
+elements with the same tag may be used in sequence. The information elements
+shall be sent in the given order. Nevertheless after the generic part the
+receiver shall be able to received them in any order. Unknown IE shall be
+ignored.
+
+==== Send Authentication Info Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+==== Send Authentication Info Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Send Authentication Info Response
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|03|Auth Tuple|<<gsup-ie-authtuple>>|0-5|TLV|36
+|===
+
+==== Update Location Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+==== Update Location Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Update Location Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|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>>|1-10|TLV|
+|===
+
+If the PDP info complete IE is present, the old PDP info list shall be cleared.
+
+==== Location Cancellation Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|06|Cancellation type|<<gsup-ie-canctype>>|O|TLV|3
+|===
+
+==== Location Cancellation Result
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+==== Purge MS Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|09|HLR Number|<<gsup-ie-hlr>>|M|TLV|0-9
+|===
+
+==== Purge MS Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Purge MS Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|07|Freeze P-TMSI|<<gsup-ie-empty>>|M|TLV|2
+|===
+
+==== Insert Subscriber Data Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|04|PDP info complete|<<gsup-ie-empty>>|M|TLV|2
+|05|PDP info|<<gsup-ie-pdpinfo>>|0-10|TLV|
+|===
+
+If the PDP info complete IE is present, the old PDP info list shall be cleared.
+
+==== Insert Subscriber Data Error
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Insert Subscriber Data Result
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+==== Delete Subscriber Data Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|10|PDP context id|<<gsup-ie-pdpinfo>> (no conditional IE)|0-10|TLV|
+|===
+
+==== Delete Subscriber Data Error
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,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
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Delete Subscriber Data Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,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
+|===
+
+=== Information Elements
+
+[[gsup-ie-msgtype]]
+==== Message Type
+
+[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
+|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
+|===
+
+[[gsup-ie-ipaddr]]
+==== 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
+'IETF allocated address'.
+
+[[gsup-ie-pdpinfo]]
+==== PDP Info
+
+This is a container for information elements describing a single PDP.
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+| |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
+|12|Access Point Name|3GPP TS 04.08, Ch. 10.5.6.1|C|TLV|3-102
+|13|Quality of Service|<<gsup-ie-qos>>|O|TLV|1-20
+|===
+
+The conditional IE are mandantory unless mentioned otherwise.
+
+[[gsup-ie-pdptype]]
+==== PDP Type
+
+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.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length (2)
+ 16-19: Spare
+ 20-23: PDP type org
+ 24-31: PDP type number
+}
+----
+
+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.
+
+Examples:
+
+* IPv4: PDP type org: 1 (IETF), PDP type number: 0x21
+* IPv6: PDP type org: 1 (IETF), PDP type number: 0x57
+
+[[gsup-ie-pdpctxid]]
+==== PDP Context ID
+
+The PDP type context ID IE consists of a single integer byte wrapped in
+a TLV.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP context ID IEI
+ 7: Res
+ 8-15: Length (1)
+ 16-23: PDP Context ID
+}
+----
+
+[[gsup-ie-authtuple]]
+==== Auth tuple
+
+This is a container for information elements describing a single authentication
+tuple.
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+| |Auth Tuple IEI|<<gsup-iei>>|M|V|1
+| |Length of Auth Tuple IE||M|V|1
+|20|RAND|<<gsup-ie-rand>>|M|TLV|18
+|21|SRES|<<gsup-ie-sres>>|M|TLV|6
+|22|Kc|<<gsup-ie-kc>>|M|TLV|10
+|===
+
+[[gsup-ie-rand]]
+==== RAND
+
+The 16-byte Random Challenge of the GSM Authentication Algorithm.
+
+[[gsup-ie-sres]]
+==== SRES
+
+The 4-byte Authentication Result of the GSM Authentication Algorithm.
+
+[[gsup-ie-kc]]
+==== Kc
+
+The 8-byte Encryption Key of the GSM Authentication and Key Agreemnt
+Algorithm.
+
+[[gsup-ie-canctype]]
+==== Cancellation Type
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length (1)
+ 16-23: Canc. Type Nr.
+}
+----
+
+.Cancellation Type Number
+[options="header",cols="10%,90%"]
+|===
+|Number|Description
+|0x00|Update Procedure
+|0x01|Subscription Withdrawn
+|===
+
+[[gsup-iei]]
+==== IE Identifier (informational)
+
+These are the standard values for the IEI. See the message definitions for the
+IEI that shall be used for the encoding.
+
+.GSUP IE Identifiers
+[options="header",cols="15%,35%,50%"]
+|===
+|IEI|Info Element|Type / Encoding
+|0x01|IMSI|Mobile Identity, 3GPP TS 04.08 Ch. 10.5.1.4
+|0x02|Cause|<<gsup-ie-cause>>
+|0x03|Auth Tuple|<<gsup-ie-authtuple>>
+|0x04|PDP Info Compl|<<gsup-ie-empty>>
+|0x05|PDP Info|<<gsup-ie-pdpinfo>>
+|0x06|Cancel Type|<<gsup-ie-canctype>>
+|0x07|Freeze P-TMSI|<<gsup-ie-empty>>
+|0x08|MSISDN|ISDN-AddressString/octet, <<gsup-ie-msisdn>>
+|0x09|HLR Number|<<gsup-ie-hlr>>
+|0x10|PDP Context ID|<<gsup-ie-pdpctxid>>
+|0x11|PDP Type|<<gsup-ie-pdptype>>
+|0x12|QoS|<<gsup-ie-qos>>
+|0x20|RAND|<<gsup-ie-rand>>
+|0x21|SRES|<<gsup-ie-sres>>
+|0x22|Kc|<<gsup-ie-kc>>
+|===
+
+[[gsup-ie-empty]]
+==== Empty field
+
+This is used for flags, if and only if this IE is present, the flag is set.
+The semantics depend on the IEI and the context.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length (0)
+}
+----
+
+[[gsup-ie-imsi]]
+==== 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.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length of IE content
+ 16-19: Digit 1
+ 20-23: Digit 2
+ 24-27: Digit ...
+ 28-31: Digit N
+ 32-39: see Note
+}
+----
+
+NOTE: Either '1 1 1 1 | Number digit N' (N odd) or 'Number digit N |
+Number digit N-1' (N even), where N is the number of digits.
+
+[[gsup-ie-msisdn]]
+==== 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 and then passed as is
+to the GGSN during the activation of the primary PDP Context.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length of IE content
+ 16-19: NPI
+ 20-22: TON
+ 23: ext
+ 24-27: Digit 1
+ 28-31: Digit 2
+ 32-35: Digit ...
+ 36-39: Digit N
+}
+----
+
+[[gsup-ie-qos]]
+==== Quality of Service Subscribed Service
+
+This encodes the subscribed QoS of a subscriber. It will be used by the
+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.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length of IE content
+ 16-23: Payload
+}
+----
+
+[[gsup-ie-hlr]]
+==== HLR Number encoded as 3GPP TS 09.02 ISDN-AddressString
+
+The HLR Number is encoded as an ISDN-AddressString in 3GPP TS 09.02. It
+will be stored by the SGSN can be used by the CDR module to keep a
+record.
+
+[packetdiag]
+----
+{
+ colwidth = 8
+ node_height = 24
+
+ 0-6: PDP type IEI
+ 7: Res
+ 8-15: Length of IE content
+ 16-19: NPI
+ 20-22: TON
+ 23: ext
+ 24-27: Digit 1
+ 28-31: Digit 2
+ 32-35: Digit ...
+ 36-39: Digit N
+}
+----
+
+[[gsup-ie-cause]]
+==== Cause
+
+This IE shall be encoded according to the 'GMM Cause' as described in
+Chapter 10.5.5.14 of 3GPP TS 04.08.
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..566124a
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,126 @@
+[[chapter_introduction]]
+== Overview
+
+[[intro_overview]]
+=== About OsmoSGSN
+
+OsmoSGSN is the Osmocom implementation of the GPRS SGSN (Serving Gprs
+Support Node) element inside the GPRS network. The SGSN plays a similar
+central function to the GPRS network as the MSC plays in the GSM
+network.
+
+The SGSN is connected on the downlink side to Gb interfaces of the BSS,
+specifically the PCU inside the BSS. The SGSN is further connected by
+the GTP protocol to the GGSN which terminates the tunnels towards the
+external packet data network (e.g. IPv4).
+
+OsmoSGSN supports both a PCU that is co-located with(in) the BTS, as
+well as a PCU that is co-located with(in) the BSC. In combination with
+OsmoNITB/OsmoBSC/OsmoBTS, the PCU is co-located within the BTS.
+
+[[fig-gprs-pcubts]]
+.GPRS network architecture with PCU in BTS
+[graphviz]
+----
+digraph G {
+ rankdir=LR;
+ MS0 [label="MS"]
+ MS1 [label="MS"]
+ MS0->BTS [label="Um"]
+ MS1->BTS [label="Um"]
+ BTS->BSC [label="Abis"]
+ BSC->MSC [label="A"]
+ BTS->PCU [label="pcu_sock"]
+ PCU->SGSN [label="Gb"]
+ SGSN->GGSN [label="GTP"]
+}
+----
+
+=== Software Components
+
+OsmoNITB contains a variety of different software components, which
+we'll quickly describe in this section.
+
+==== Gb Implementation
+
+OsmoSGSN implements the ETSI/3GPP specified Gb interface, including TS
+08.16 (NS), TS 08.18 (BSSGP) and TS 08.64 (LLC) protocols. As transport
+layers for NS, it supports NS/IP (NS encapsulated in UDP/IP), as well as
+NS/FR/GRE/IP. The latter is provided in order to use a Router with
+Ethernet and Frame Relay interface to convert to actual physical Frame
+Relay medium, which is not directly supported by OsmoSGSN.
+
+The actual Gb Implementation is part of the libosmogb library, which is
+in turn part of the libosmocore software package. This allows the same
+Gb implementation to be used from osmo-pcu, osmo-gbproxy as well as
+OsmoSGSN.
+
+
+==== GTP Implementation
+
+OsmoSGSN uses the libgtp implementation originating from OpenGGSN. It
+supports both GTPv0 and GTPv1.
+
+
+==== GMM Implementation
+
+The GPRS Mobility Management implementation is quite simplistic at this
+point. It supports the GPRS ATTACH and GPRS ROUTING AREA UPDATE
+procedures, as well as GPRS ATTACH and GPRS DETACH.
+
+However, as the SGSN currently does not implement any type of HLR
+access, it is not able to authenticate a subscriber or even check if the
+subscriber exists at all. As such, all non-roaming subscribes are
+allowed to attach to OsmoSGSN. Non-roaming means that the first 5
+digits of the IMSI must match the MCC and MNC of the cell that the
+subscriber is registering to.
+
+
+==== LLC Implementation
+
+The LLC (Logical Link Control) implementation of OsmoSGSN only supports
+non-acknowledged mode, as this is the most common use case in real-world
+GPRS networks.
+
+Furthermore, it does not support IP header nor payload compression at
+this point. Addition of those features is subject to customer demand or
+user/customer contributions.
+
+The LLC implementation does support LLC encryption. However, as no HLR
+access is implemented yet, there is no way to enable/configure
+per-subscriber specific keys.
+
+
+==== Session Management Implementation
+
+The session management procedures ACTIVATE PDP CONTEXT and DEACTIVATE
+PDP CONTEXT are supported. However, no MODIFY PDP CONTEXT and no
+Network-initiated PDP context activation is possible. This is again
+covering the predominant use cases and configurations in GPRS real-world
+networks while skipping the more esoteric features.
+
+Multiple PDP contexts can be attached by a single MS.
+
+Currently, all PDP contexts are routed to the same GGSN, irrespective of
+the APN used/configured in the MS. This is sufficient (and actually
+desirable) for small autonomous networks, but of course not suitable for
+real networks in roaming scenarios. Please contact sysmocom in case you
+require additional features such as DNS-based APN resolving.
+
+=== Limitations
+
+At the time of writing, OsmoSGSN still has a number of limitations,
+which are a result of the demand-driven Open Source development model.
+If you require any of those features, please consider implementing and
+contributing them, or contracting the existing OsmoSGSN developers for
+performing that work.
+
+Known Limitations include:
+
+* No LLC encryption support
+* No interface to the OsmoNITB HLR
+* No paging coordination between SGSN and MSC
+* No SMS over Ps support
+* No IuPS interface for 3G (in progress)
+* No IP header compression
+* No payload compression
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..d758b28
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,35 @@
+== Running OsmoSGSN
+
+The OsmoSGSN executable (`osmo-sgsn`) offers the following command-line
+options:
+
+
+=== SYNOPSIS
+
+*osmo-sgsn* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-e 'LOGLEVEL']
+
+
+=== OPTIONS
+
+*-h, --help*::
+ Print a short help message about the supported options
+*-V, --version*::
+ Print the compile-time version number of the OsmoBTS program
+*-d, --debug 'DBGMASK','DBGLEVELS'*::
+ Set the log subsystems and levels for logging to stderr. This
+ has mostly been superseded by VTY-based logging configuration,
+ see <<logging>> for further information.
+*-D, --daemonize*::
+ Fork the process as a daemon into background.
+*-c, --config-file 'CONFIGFILE'*::
+ Specify the file and path name of the configuration file to be
+ used. If none is specified, use `osmo_sgsn.cfg` in the current
+ working directory.
+*-s, --disable-color*::
+ Disable colors for logging to stderr. This has mostly been
+ deprecated by VTY based logging configuration, see <<logging>>
+ for more information.
+*-e, --log-level 'LOGLEVEL'*::
+ Set the global log level for logging to stderr. This has mostly
+ been deprecated by VTY based logging configuration, see
+ <<logging>> for more information.