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.