move project specific manuals to their own repososmith/move-manuals-to-project-repos

Build manuals when ./configure --enable-manuals is specified. Requires
osmo-gsm-manuals to be installed.

Related: OS#3385
Depends: I96933dd4dd6cac159847647f1c642215051a9aad (osmo-gsm-manuals)
Change-Id: I2f9c27f81940b02414f0e618483bffade72e8cf7

6 files changed, 504 insertions, 0 deletions

diff --git a/doc/manuals/chapters/control.adoc b/doc/manuals/chapters/control.adoc
new file mode 100644
index 000000000..af03be7df
--- /dev/null
+++ b/doc/manuals/chapters/control.adoc
@@ -0,0 +1,31 @@
+[[control]]
+== Control interface
+
+The actual protocol is described in <<common-control-if>>, the variables common
+to all programs using it are described in <<ctrl_common_vars>>. This section
+describes the CTRL interface variables specific to OsmoMSC.
+
+.Variables available on OsmoMSC's Control interface
+[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
+|===
+|Name|Access|Trap|Value|Comment
+|subscriber-list-active-v1|RO|No||Return list of active subscribers.
+|===
+
+=== subscriber-list-active-v1
+
+Return a list of subscribers that are successfully attached (including full
+successful authentication and ciphering if those are enabled).
+
+The reply comprises of one subscriber per line, of the format
+
+----
+<IMSI>,<MSISDN>\n[<IMSI>,<MSISDN>\n[...]]
+----
+
+For example:
+
+----
+901700000015252,22801
+901700000015253,22802
+----
diff --git a/doc/manuals/chapters/counters.adoc b/doc/manuals/chapters/counters.adoc
new file mode 100644
index 000000000..7fbb10c6f
--- /dev/null
+++ b/doc/manuals/chapters/counters.adoc
@@ -0,0 +1,4 @@
+[[counters]]
+== Counters
+
+include::./counters_generated.adoc[]
diff --git a/doc/manuals/chapters/counters_generated.adoc b/doc/manuals/chapters/counters_generated.adoc
new file mode 100644
index 000000000..afeb8ffe5
--- /dev/null
+++ b/doc/manuals/chapters/counters_generated.adoc
@@ -0,0 +1,40 @@
+// autogenerated by show asciidoc counters
+These counters and their description based on OsmoMSC UNKNOWN (OsmoMSC).
+
+// generating tables for rate_ctr_group
+// rate_ctr_group table mobile switching center
+.msc - mobile switching center 
+[options="header"]
+|===
+| Name | Reference | Description
+| loc_update_type:attach | <<msc_loc_update_type:attach>> | Received location update imsi attach requests.
+| loc_update_type:normal | <<msc_loc_update_type:normal>> | Received location update normal requests.
+| loc_update_type:periodic | <<msc_loc_update_type:periodic>> | Received location update periodic requests.
+| loc_update_type:detach | <<msc_loc_update_type:detach>> | Received location update detach indication.
+| loc_update_resp:failed | <<msc_loc_update_resp:failed>> | Rejected location updates.
+| loc_update_resp:completed | <<msc_loc_update_resp:completed>> | Successful location updates.
+| sms:submitted | <<msc_sms:submitted>> | Received a RPDU from a MS (MO).
+| sms:no_receiver | <<msc_sms:no_receiver>> | Counts SMS which couldn't routed because no receiver found.
+| sms:delivered | <<msc_sms:delivered>> | Global SMS Deliver attempts.
+| sms:rp_err_mem | <<msc_sms:rp_err_mem>> | CAUSE_MT_MEM_EXCEEDED errors of MS responses on a sms deliver attempt.
+| sms:rp_err_other | <<msc_sms:rp_err_other>> | Other error of MS responses on a sms delive attempt.
+| sms:deliver_unknown_error | <<msc_sms:deliver_unknown_error>> | Unknown error occured during sms delivery.
+| call:mo_setup | <<msc_call:mo_setup>> | Received setup requests from a MS to init a MO call.
+| call:mo_connect_ack | <<msc_call:mo_connect_ack>> | Received a connect ack from MS of a MO call. Call is now succesful connected up.
+| call:mt_setup | <<msc_call:mt_setup>> | Sent setup requests to the MS (MT).
+| call:mt_connect | <<msc_call:mt_connect>> | Sent a connect to the MS (MT).
+| call:active | <<msc_call:active>> | Count total amount of calls that ever reached active state.
+| call:complete | <<msc_call:complete>> | Count total amount of calls which got terminated by disconnect req or ind after reaching active state.
+| call:incomplete | <<msc_call:incomplete>> | Count total amount of call which got terminated by any other reason after reaching active state.
+|===
+// generating tables for osmo_stat_items
+// generating tables for osmo_counters
+// ungrouped osmo_counters
+.ungrouped osmo counters
+[options="header"]
+|===
+| Name | Reference | Description
+| msc.active_calls | <<ungroup_counter_msc.active_calls>> | 
+|===
+
+
diff --git a/doc/manuals/chapters/net.adoc b/doc/manuals/chapters/net.adoc
new file mode 100644
index 000000000..06be4bad2
--- /dev/null
+++ b/doc/manuals/chapters/net.adoc
@@ -0,0 +1,154 @@
+[[net]]
+== Configuring the Core Network
+
+The core network parameters are configured by the config file (as in `osmo-msc
+-c osmo-msc.cfg`). The config file is parsed by the VTY, which is also
+available via telnet in the running `osmo-msc` instance. Be aware that even
+though you may be able to change these parameters without restarting
+`osmo-msc`, some may not take immediate effect, and it is safest to use the
+config file to have these parameters set at startup time.
+
+The core network parameters are found in the `config` / `network`.
+
+A full reference to the available commands can be found in the _OsmoMSC VTY
+reference manual_ <<vty-ref-osmomsc>>. This section describes only the most
+commonly used settings.
+
+Here is an overview of the config items, described in more detail below:
+
+----
+network
+ network country code 262
+ mobile network code 89
+ mm info 1
+ short name OsmoMSC
+ long name OsmoMSC
+ authentication required
+ encryption a5 3
+----
+
+[TIP]
+====
+Use the telnet VTY interface to query the current configuration of a running
+`osmo-msc` process:
+
+----
+$ telnet localhost 4254
+OsmoMSC> enable
+OsmoMSC# show running-config
+----
+
+Some parameters may be changed without restarting `osmo-msc`. To reach the
+`network` node, enter:
+
+----
+OsmoMSC> enable
+OsmoMSC# configure terminal
+OsmoMSC(config)# network
+OsmoMSC(config-net)# short name Example-Name
+OsmoMSC(config-net)# exit
+OsmoMSC(config)#
+----
+
+The telnet VTY features tab-completion as well as context sensitive help shown
+when entering a `?` question mark.
+
+You can always use the `list` VTY command or enter `?` on the blank prompt to
+get a list of all possible commands at the current node.
+====
+
+
+=== MCC/MNC
+
+The key identities of every GSM PLMN is the Mobile Country Code and the Mobile
+Network Code. They are identical over the entire network. In most cases, the
+MCC/MNC will be allocated to the operator by the respective local regulatory
+authority. For example, to set the MCC/MNC of 262-89, have this in your
+osmo-msc.cfg:
+
+----
+network
+ network country code 262
+ mobile network code 89
+----
+
+
+=== Configuring MM INFO
+
+The _MM INFO_ procedure can be used after a successful _LOCATION UPDATE_ in
+order to transmit the human-readable network name as well as local time zone
+information to the MS.  By default, _MM INFO_ is not active, i.e. `0`. Set to `1`
+to activate this feature:
+
+----
+network
+ mm info 1
+ short name OsmoMSC
+ long name OsmoMSC
+----
+
+[NOTE]
+====
+Not all phones support the MM INFO procedure. If a phone is not
+factory-programmed to contain the name for your MCC/MNC, it will likely only
+provide a numeric display of the network name, such as _262-89_, or show the
+country code transformed into a letter, such as _D 89_.
+====
+
+The time information transmitted is determined by the local system time of the
+operating system on which OsmoMSC is running.
+
+
+=== Authentication
+
+Authorized subscribers must be entered in the HLR database, see the _OsmoHLR
+reference manual_ <<userman-osmohlr>>. If authentication tokens (such as KI for
+2G, or K and OP/OPC for UMTS) are present in the HLR, OsmoMSC will only attach
+a subscriber after successful authentication.
+
+If no authentication keys are present in the HLR for a given subscriber,
+OsmoMSC will attach the subscriber _without_ authentication. You can reject
+subscribers that lack authentication info in the HLR with this setting:
+
+----
+network
+ authentication required
+----
+
+=== Ciphering
+
+To enable ciphering on the radio link, authentication must take place first:
+the Kc resulting from authentication is the key used for ciphering. Hence, all
+subscribers must have authentication tokens available in the HLR for ciphering.
+
+The MS, BTS and MSC must agree on a ciphering algorithm to use.
+
+- The MS sends its supported ciphering algorithms via Classmark IEs during
+  Location Updating.
+- Typically the BSC needs to know which A5 ciphers are supported by connected
+  BTSes.
+- Finally, OsmoMSC may impose that specific A5 ciphers shall not be considered.
+
+It is the responsibility of the BSC to then pick an A5 cipher that satisfies
+all requirements.
+
+- In OsmoMSC, A5/0 means that ciphering is turned off.
++
+----
+network
+ encryption a5 0
+----
+
+- A5/1 and A5/3 are currently supported by Osmocom.
++
+----
+network
+ encryption a5 3
+----
+
+- Never use A5/2: it is an "export grade cipher" and has been deprecated for
+  its low ciphering strength.
+
+NOTE: At the time of writing, OsmoMSC supports setting only a single A5 cipher,
+while it should be able to allow a set of ciphers. This is subject to ongoing
+development.
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 000000000..0bb47d72d
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,127 @@
+[[overview]]
+== Overview
+
+This manual should help you getting started with OsmoMSC. It will cover
+aspects of configuring and running the OsmoMSC.
+
+[[intro_overview]]
+=== About OsmoMSC
+
+OsmoMSC is the Osmocom implementation of a Mobile Switching Center (MSC) for 2G
+and 3G GSM and UMTS mobile networks. Its interfaces are:
+
+- GSUP towards OsmoHLR (or a MAP proxy);
+- A over IP towards a BSC (e.g. OsmoBSC);
+- IuCS towards an RNC or HNB-GW (e.g. OsmoHNBGW) for 3G voice;
+- MNCC (Mobile Network Call Control derived from GSM TS 04.07);
+- SMPP 3.4 (Short Message Peer-to-Peer);
+- The Osmocom typical telnet VTY and CTRL interfaces.
+
+OsmoMSC originated from the OpenBSC project, which started as a minimalistic
+all-in-one implementation of the GSM Network. In 2017, OpenBSC had reached
+maturity and diversity (including M3UA SIGTRAN and 3G support in the form of
+IuCS and IuPS interfaces) that naturally lead to a separation of the all-in-one
+approach to fully independent separate programs as in typical GSM networks.
+Before it was split off, OsmoMSC originated from libmsc of the old openbsc.git.
+Since a true _A_ interface and IuCS for 3G support is available, OsmoMSC
+exists only as a separate standalone entity.
+
+Key differences of the new OsmoMSC compared to the old OsmoNITB are:
+
+- The complete VLR implementation that communicates with the separate HLR
+  (OsmoHLR) for subscriber management. In contrast to the OsmoNITB, HLR queries
+  are fully asynchronous, and the separate HLR allows using centralized
+  subscriber management for both circuit-switched and packet-switched domains
+  (i.e. one OsmoHLR for both OsmoMSC and OsmoSGSN).
+
+- VLR and HLR brought full UMTS AKA (Authentication and Key Agreement) support,
+  i.e. Milenage authentication in both the full 3G variant as well as the
+  backwards compatible 2G variant.
+
+- Addition of a true _A_ interface for 2G voice services. Previously, OsmoBSC
+  had an SCCPlite based _A_ interface towards 3rd party MSC implementations.
+  OsmoMSC features a true SCCP/M3UA _A_ interface, which allows running OsmoBSC
+  against this Osmocom based MSC implementation. The new SCCP/M3UA SIGTRAN for
+  the _A_ interface is implemented in libosmo-sccp, which is used by OsmoMSC
+  and OsmoBSC (and others), to establish a link via an STP (e.g. OsmoSTP).
+
+- Addition of an _IuCS_ interface to allow operating 3G voice services, also
+  via SCCP/M3UA SIGTRAN, for example connecting via OsmoHNBGW to a 3G small
+  cell device.
+
+Find the OsmoMSC issue tracker and wiki online at
+
+- https://osmocom.org/projects/osmomsc
+- https://osmocom.org/projects/osmomsc/wiki
+
+
+[[fig-gsm]]
+.Typical GSM network architecture used with OsmoMSC
+[graphviz]
+----
+digraph G {
+	rankdir=LR;
+	MS0 [label="MS"]
+	MS1 [label="MS"]
+	MS2 [label="MS"]
+	MS3 [label="MS"]
+	UE0 [label="UE"]
+	UE1 [label="UE"]
+	BTS0 [label="BTS"]
+	BTS1 [label="BTS"]
+	STP [label="STP\n(SCCP routing)"]
+	HLR [label="HLR+AUC+EIR"]
+	HNB [label="RNC or hNodeB"]
+	MGW
+	MS0->BTS0 [label="Um"]
+	MS1->BTS0 [label="Um"]
+	MS2->BTS1 [label="Um"]
+	MS3->BTS1 [label="Um"]
+	UE0->HNB
+	UE1->HNB
+	BTS0->BSC [label="Abis"]
+	BTS1->BSC [label="Abis"]
+	BSC->STP [label="A/SCCP/M3UA"]
+	STP->MSC [label="A/SCCP/M3UA"]
+	STP->MSC [label="IuCS/SCCP/M3UA"]
+	VLR->HLR [label="GSUP"]
+	HNB->HNBGW [label="Iuh"]
+	HNBGW->STP [label="IuCS/SCCP/M3UA"]
+	MSC->MGW [label="MGCP"]
+	BTS0->MGW [label="RTP"]
+	BTS1->MGW [label="RTP"]
+	subgraph cluster_msc {
+		label = "OsmoMSC";
+		MSC->SMSC;
+		MSC->VLR
+	}
+}
+----
+
+
+=== Software Components
+
+This is a brief description of OsmoMSC's internal software components.
+
+==== SMSC
+
+A minimal store-and-forward server for SMS, supporting both MO and MT
+SMS service, as well as multi-part messages.
+
+The built-in SMSC also supports an external SMSC interface.  For more
+information, see <<smpp>>.
+
+==== MSC
+
+The MSC component implements the mobility management (MM) functions of the TS
+04.08 and delegates to SMSC for SMS message handling and the VLR for subscriber
+management.
+
+Furthermore, it can handle TS 04.08 Call Control (CC), either by use of
+an internal MNCC handler, or by use of an external MNCC agent.  For more
+information see <<mncc>>.
+
+==== VLR
+
+A fully featured Visitor Location Register handles the subscriber management
+and authentication, and interfaces via GSUP to the external HLR.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 000000000..8656a586b
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,148 @@
+== Running OsmoMSC
+
+The OsmoMSC executable (`osmo-msc`) offers the following command-line
+arguments:
+
+=== SYNOPSIS
+
+*osmo-msc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'DATABASE'] [-M 'SOCKETPATH'] [-C]
+
+=== 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 `openbsc.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.
+*-T, --timestamp*::
+	Enable time-stamping of log messages 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.
+*-l, --database 'DATABASE'*::
+	Specify the file name of the SQLite3 database to use as SMS storage
+*-M, --mncc-sock-path*::
+	Enable the MNCC socket for an external MNCC handler. See
+	<<mncc>> for further information.
+*-m, --mncc-sock*::
+	Same as option -M (deprecated).
+*-C, --no-dbcounter*::
+	Disable the regular periodic synchronization of statistics
+	counters to the database.
+
+
+=== Multiple instances
+
+Running multiple instances of `osmo-msc` on the same computer is possible if all
+interfaces (VTY, CTRL) are separated using the appropriate configuration
+options. The IP based interfaces are binding to local host by default. In order
+to separate the processes, the user has to bind those services to specific but
+different IP addresses and/or ports.
+
+The VTY and the Control interface can be bound to IP addresses from the loopback
+address range, for example:
+
+----
+line vty
+ bind 127.0.0.2
+ctrl
+ bind 127.0.0.2
+----
+
+If external SMPP is enabled, you may bind it to a different interface using:
+
+----
+smpp
+ local-tcp-ip 10.23.42.1 2775
+----
+
+More on SMPP configuration in <<smpp-config-global>>.
+
+The external MNCC handler is configured by the `--mncc-sock` commandline
+argument. Choose a different such socket path for each OsmoMSC instance running
+on the same file system. See more in <<mncc-external>>.
+
+For the following links, OsmoMSC acts as a client and does not listen/bind to a
+specific interface, and will hence not encounter conflicts for multiple instances
+running on the same interface:
+
+- The SCCP/M3UA links are established by OsmoMSC contacting an STP.
+- The GSUP link is established by OsmoMSC contacting an HLR.
+
+
+=== Configure primary links
+
+==== Configure SCCP/M3UA to accept _A_ and _IuCS_ links
+
+OsmoMSC will contact an STP instance to establish an SCCP/M3UA link. BSC and
+HNBGW will then reach the MSC via this link. By default, an STP instance is
+assumed to listen on the default M3UA port (2905) on the local host.
+
+Establishing an SCCP/M3UA link towards an STP instance not on the local host
+can be configured as follows:
+
+----
+cs7 instance 0
+ asp my-OsmoMSC 2905 0 m3ua
+  ! IP address of the remote STP:
+  remote-ip 10.23.24.1
+----
+
+Note that _A_ and _IuCS_ may use different SCCP instances, if so desired:
+
+----
+cs7 instance 0
+ asp my-OsmoMSC-A 2905 0 m3ua
+  remote-ip 10.23.42.1
+cs7 instance 1
+ asp my-OsmoMSC-Iu 2905 0 m3ua
+  remote-ip 10.23.42.2
+msc
+ cs7-instance-a 0
+ cs7-instance-iu 1
+----
+
+A full configuration needs an `asp` on an `as` -- an Application Server Process
+running on an Application Server -- as well as a local point code and routing
+configuration. The SCCP VTY automatically creates those parts that are missing,
+by assuming sane defaults. A complete configuration would look like this:
+
+----
+cs7 instance 0
+ point-code 0.23.1
+ asp my-OsmoMSC-A-Iu 2905 0 m3ua
+  remote-ip 127.0.0.1
+ as my-as-for-OsmoMSC-A-Iu m3ua
+  asp my-OsmoMSC-A-Iu
+  routing-key 0 0.23.1
+----
+
+==== Configure GSUP to reach the HLR
+
+OsmoMSC will assume a GSUP server (OsmoHLR) to run on the local host and the
+default GSUP port (4222). Contacting an HLR at a different IP address can be
+configured as follows:
+
+----
+hlr
+ ! IP address of the remote HLR:
+ remote-ip 10.23.42.1
+ ! default port is 4222, optionally configurable by:
+ remote-port 1234
+----