diff options
Diffstat (limited to 'manuals/OsmoNITB/chapters')
| -rw-r--r-- | manuals/OsmoNITB/chapters/bts-examples.adoc | 281 | ||||
| -rw-r--r-- | manuals/OsmoNITB/chapters/control.adoc | 57 | ||||
| -rw-r--r-- | manuals/OsmoNITB/chapters/hlr.adoc | 331 | ||||
| -rw-r--r-- | manuals/OsmoNITB/chapters/net.adoc | 139 | ||||
| -rw-r--r-- | manuals/OsmoNITB/chapters/overview.adoc | 196 | ||||
| -rw-r--r-- | manuals/OsmoNITB/chapters/running.adoc | 104 |
6 files changed, 1108 insertions, 0 deletions
diff --git a/manuals/OsmoNITB/chapters/bts-examples.adoc b/manuals/OsmoNITB/chapters/bts-examples.adoc new file mode 100644 index 000000000..b15fb9921 --- /dev/null +++ b/manuals/OsmoNITB/chapters/bts-examples.adoc @@ -0,0 +1,281 @@ +[[bts-examples]] +== OsmoNITB example configuration files + +The `openbsc/doc/examples/osmo-nitb` directory in the OpenBSC source +tree contains a collection of example configuration files, sorted by BTS +type. + +This chapter is illustrating some excerpts from those examples + +[[bts_example_bs11]] +=== Example configuration for OsmoNITB with one dual-TRX BS-11 + +.OsmoNITB with BS11, 2 TRX, no frequency hopping +==== + +---- +e1_input + e1_line 0 driver misdn +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + timer t3101 10 + timer t3113 60 + bts 0 + type bs11 <1> + band GSM900 + cell_identity 1 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + oml e1 line 0 timeslot 1 sub-slot full <2> + oml e1 tei 25 <3> + trx 0 + arfcn 121 + max_power_red 0 + rsl e1 line 0 timeslot 1 sub-slot full <4> + rsl e1 tei 1 <5> + timeslot 0 + phys_chan_config CCCH+SDCCH4 + e1 line 0 timeslot 1 sub-slot full + timeslot 1 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 1 <6> + timeslot 2 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 2 + timeslot 3 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 3 + timeslot 4 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 0 + timeslot 5 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 1 + timeslot 6 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 2 + timeslot 7 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 3 + trx 1 + arfcn 123 + max_power_red 0 + rsl e1 line 0 timeslot 1 sub-slot full <4> + rsl e1 tei 2 <5> + timeslot 0 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 0 <6> + timeslot 1 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 1 + timeslot 2 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 2 + timeslot 3 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 3 + timeslot 4 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 0 + timeslot 5 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 1 + timeslot 6 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 2 + timeslot 7 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 3 +---- +==== + +<1> The BTS type must be set to __bs11__ +<2> The OML E1 timeslot needs to be identical with what was on the BTS side using LMT. +<3> The OML TEI value needs to be identical with what was configured on the BTS side using LMT. +<4> The RSL E1 timeslot can be identical for all TRX. +<5> The RSL TEI values __must__ be different if multiple TRX share one E1 signalling timeslot. +<6> The TCH all need to be allocated one 16k sub-slot on the E1 + +[[bts_example_nbts]] +=== Example configuration for OsmoNITB with one single-TRX nanoBTS + +.OsmoNITB with one single-TRX nanoBTS +==== + +---- +e1_input + e1_line 0 driver ipa <1> +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + auth policy closed + location updating reject cause 13 + encryption a5 0 + neci 1 + rrlp mode none + mm info 1 + handover 0 + bts 0 + type nanobts <2> + band DCS1800 <3> + cell_identity 0 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + ms max power 15 + cell reselection hysteresis 4 + rxlev access min 0 + channel allocator ascending + rach tx integer 9 + rach max transmission 7 + ip.access unit_id 1801 0 <4> + oml ip.access stream_id 255 line 0 + gprs mode none + trx 0 + rf_locked 0 + arfcn 871 <5> + nominal power 23 + max_power_red 20 <6> + rsl e1 tei 0 + timeslot 0 + phys_chan_config CCCH+SDCCH4 + timeslot 1 + phys_chan_config SDCCH8 + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F +---- +==== + +<1> You have to configure one virtual E1 line with the + IPA driver in order to use Abis/IP. One e1_line is + sufficient for any number of A-bis/IP BTSs, there is no + limit like in physical E1 lines. +<2> The BTS type must be set using `type nanobts` +<3> The GSM band must be set according to the BTS hardware. +<4> The IPA Unit ID parameter must be set to what has been configured on + the BTS side using the __BTS Manager__ or `ipaccess-config`. +<5> The ARFCN of the BTS. +<6> All known nanoBTS units have a nominal transmit power of 23 dBm. If + a `max_power_red` of 20 (dB) is configured, the resulting output + power at the BTS Tx port is 23 - 20 = 3 dBm. + +[NOTE] +==== +The `nominal_power` setting does __not__ influence the transmitted power +to the BTS! It is a setting by which the system administrator tells the +BSC about the nominal output power of the BTS. The BSC uses this as +basis for calculations. +==== + + +[[bts_example_nbts_multi]] +=== Example configuration for OsmoNITB with multi-TRX nanoBTS + +.OsmoNITB configured for dual-TRX (stacked) nanoBTS +==== + +---- +e1_input + e1_line 0 driver ipa +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + auth policy closed + location updating reject cause 13 + encryption a5 0 + neci 1 + rrlp mode none + mm info 0 + handover 0 + bts 0 + type nanobts + band DCS1800 + cell_identity 0 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + ms max power 15 + cell reselection hysteresis 4 + rxlev access min 0 + channel allocator ascending + rach tx integer 9 + rach max transmission 7 + ip.access unit_id 1800 0 <1> + oml ip.access stream_id 255 line 0 + gprs mode none + trx 0 + rf_locked 0 + arfcn 871 + nominal power 23 + max_power_red 0 + rsl e1 tei 0 + timeslot 0 + phys_chan_config CCCH+SDCCH4 + timeslot 1 + phys_chan_config SDCCH8 + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F + trx 1 + rf_locked 0 + arfcn 873 + nominal power 23 + max_power_red 0 + rsl e1 tei 0 + timeslot 0 + phys_chan_config SDCCH8 + timeslot 1 + phys_chan_config TCH/F + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F +---- +==== + +<1> In this example, the IPA Unit ID is specified as `1800 0`. Thus, the + first nanoBTS unit (`trx 0`) needs to be configured to 1800/0/0 and + the second nanoBTS unit (`trx 1`) needs to be configured to 1800/0/1. + You can configure the BTS unit IDs using the `ipaccess-config` + utility included in OpenBSC. + +[NOTE] +==== +For building a multi-TRX setup, you also need to connect the TIB cables +between the two nanoBTS units, as well as the coaxial/RF AUX cabling. +==== diff --git a/manuals/OsmoNITB/chapters/control.adoc b/manuals/OsmoNITB/chapters/control.adoc new file mode 100644 index 000000000..db12bbb68 --- /dev/null +++ b/manuals/OsmoNITB/chapters/control.adoc @@ -0,0 +1,57 @@ +[[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>>. The +variables shared with OsmoBSC are described in corresponding section of +OsmoBSC documentation.Here we describe variables specific to OsmoNITB. + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|subscriber-modify-v1|WO|No|"<imsi>,<msisdn>,<alg>,<ki>"|See <<sub1>> for details. +|subscriber-delete-v1|WO|No|"<imsi>"|See <<subdel>> for details. +|subscriber-list-active-v1|RO|No||Return list of active subscribers. +|=== + +[[sub1]] +=== subscriber-modify-v1 + +Modify (or add if missing) subscriber entry with the give IMSI, MSISDN, Ki and +algorithm (valid values are "none", "xor" and "comp128v1"). The subscriber is +automatically marked as authorized. + +[[subdel]] +=== subscriber-delete-v1 + +Delete the subscriber with the given IMSI. Returns "Removed active subscriber" +or "Removed" depending on the subscriber's use status. + +[[osmo-bsc_nat]] + +The following variables are only available over control interface of +osmo-bsc_nat program. + +.Variables available over control interface of osmo-bsc_nat +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|net.0.bsc.N.*|RW|Yes|Arbitrary variable|Forward given command to BSC N control interface. +|net.0.bsc_cfg.N.access-list-name|RW|No|"<name>"|Set/Get ACL for a given BSC N. +|net.0.bsc_cfg.N.no-access-list-name|WO|No|Ignored|Remove ACL for a given BSC N. +|net.0.add.allow.access-list.A|WO|No|"<regexp>"|See <<nacl>> for details. +|net.0.save-configuration|WO|No|Ignored|Save current running config into file. +|net.0.bsc.N.notification-rejection-v1|NA|Yes|"imsi=<imis>"|See <<narej>> for details. +|=== + +[[nacl]] +=== allow.access-list + +Add given regular expression for matching IMSI(s) to allowed access list A. + +[[narej]] +=== notification-rejection-v1 + +This TRAP event notifies all connected clients about IMSI which was rejected by +BSC N. diff --git a/manuals/OsmoNITB/chapters/hlr.adoc b/manuals/OsmoNITB/chapters/hlr.adoc new file mode 100644 index 000000000..8f2840a6e --- /dev/null +++ b/manuals/OsmoNITB/chapters/hlr.adoc @@ -0,0 +1,331 @@ +[[hlr]] +== OsmoNITB HLR subsystem + + +As OsmoNITB is a fully autonomous system, it also includes a +minimal/simplistic HLR and AUC. Compared to real GSM networks, it does +not implement any of the external interfaces of a real HLR, such as the +MAP/TCAP/SCCP protocol. It can only be used inside the OsmoNITB. + +While functionally maintaining the subscriber database and +authentication keys, it offers a much reduced feature set. For example, +it is not possible to configure bearer service permission lists, or +BAOC. + +At this time, the only supported database back end for the OsmoNITB +internal HLR/AUC is the file-based SQL database SQLite3. + +=== Authorization Policy + +Authorization determines how subscribers can access your network. This +is unrelated to authentication, which verifies the authenticity of SIM +cards that register with the network. + +OsmoNITB supports three different authorization policies: + +closed:: + This mode requires subscribers to have a record with their IMSI + in the HLR, and it requires that their status is set to + `authorized 1` + + + This reflects the most typical operation of GSM networks, where + subscribers have to obtain a SIM card issued by the operator. At the + time the SIM gets issued, it is provisioned in the HLR to enable the + subscriber to use the services of the network. + +accept-all:: + This policy accepts any and all subscribers that every try to + register to the network. Non-existent subscribers are + automatically and dynamically created in the HLR, and they + immediately have full access to the network. Any IMSI can + register, no matter what SIM card they are using in their + phones. + + + This mode is mostly useful for lab testing or for demonstrating + the lack of mutual authentication and the resulting security + problems in the GSM system. + +NOTE: As you do not know the Ki of dynamically created subscribers with +SIM cards of unknown origin, you cannot use cryptographic authentication +and/or encryption! + +CAUTION: Never run a network in accept-all mode, unless you know exactly +what you are doing. You are very likely causing service interruption to +mobile phones in the coverage area of your BTSs, which is punishable +under criminal law in most countries! + +token:: + This method was created for special-purpose configurations at + certain events. It tries to combine the benefits of automatic + enrollment with foreign IMSI while trying to prevent causing disruption + to phones that register to the network by accident. + + + This policy is currently not actively supported. + +The currently active policy can be selected using the +`auth policy (closed|accept-all|token)` at the `network` configuration +node of the VTY. + +=== Location Update Reject Cause + +When a 'Location Update Request' is to be rejected by the network (e.g. +due to an unknown or unauthorized subscriber), the 'Location Update +Reject' message will contain a 'Reject Cause'. + +You can configure the numeric value of that cause by means of the +`location updating reject cause <2-111>` command at the network node. + + +=== Querying information about a subscriber + +Information about a specific subscriber can be obtained from the HLR by +issuing `show subscriber` command. + +For example, to display information about a subscriber with the IMSI +602022080345046, you can use the following command: + +.Displaying information about a subscriber +---- +OpenBSC> show subscriber imsi 602022080345046 + ID: 1, Authorized: 1 <1> + Name: 'Frank' + Extension: 2342 <2> + LAC: 1/0x1 <3> + IMSI: 602022080345046 + TMSI: 4DB8B4D8 + Pending: 0 + Use count: 1 +---- + +<1> Whether or not the subscriber is authorized for access +<2> OsmoNITB is often treated like a PBX, this is why phone numbers are called extensions +<3> The Location Area Code (LAC) indicates where in the network the + subscriber has last performed a LOCATION UPDATE. Detached subscribers + indicate a LAC of 0. + +Subscribers don't have to be identified/referenced by their IMSI, but +they can also be identified by their extension (phone number), their +TMSI as well as their internal database ID. Example alternatives +showing the same subscriber record are: +---- +OpenBSC> show subscriber id 1 +---- + +or + +---- +OpenBSC> show subscriber extension 2342 +---- + + +=== Enrolling a subscriber + +A subscriber can be added to the network in different ways: + +. authorizing an auto-generated subscriber +. manually creating a subscriber using VTY commands +. manually creating subscriber by insert into SQL database by external program + +==== Authorizing an auto-generated subscriber + +If the `subscriber-create-on-demand` configuration option is set in the `nitb` +VTY config node, then OsmoNITB will automatically create a subscriber record +for every IMSI that ever tries to perform a LOCATION UPDATE with the network. +However, those subscriber records are marked as "not authorized", i.e. they +will not be able to use your network. + +You can latter on _authorize_ any such a subscriber using the `subscriber IMSI +... authorized 1` command at the VTY enable node. + +.Example: Authorizing an auto-generated subscriber +---- +OpenBSC> enable +OpenBSC# configure terminal +OpenBSC(config)# nitb +OpenBSC(config-nitb)# subscriber-create-on-demand <1> +OpenBSC(config-nitb)# end +OpenBSC# <2> +OpenBSC# subscriber imsi 262420123456789 authorized 1 <3> +---- +<1> We first ensure that `subscriber-create-on-demand` is active +<2> At this time we ensure that the MS with IMSI 262420123456789 performs a + location update to our network, e.g. by powering up the associated phone + followed by manual operator selection +<3> Here we authorize that ISMI + +The above method implies that you know the IMSI stored on the SIM card of the +subscriber that you want to to authorize. Unfortunately there is no easy/standard +way to obtain the IMSI on most phones. If the phone has an AT-command +interface, you may try `AT+CIMI`. You can also read the IMSI off the SIM using +a PC-attached smart card reader. + +NOTE: Contrary to classic GSM networks and for historic reasons, this behavior +is the default behavior of OsmoNITB. For production networks with a closed +subscriber base, it is strongly recommended to use the `no +subscriber-create-on-demand` option at the `nitb` VTY config node. + +==== Manually creating a subscriber from the VTY + +You can manually add a subscriber to the HLR by VTY commands. To do so, yo +will need to know at the minimum the IMSI of the subscriber. + +.Example: Create a new subscriber for IMSI 262429876543210 +---- +OpenBSC# subscriber create imsi 262429876543210 + ID: 3, Authorized: 0 <1> + Extension: 22150 <2> + LAC: 0/0x0 <3> + IMSI: 262429876543210 + Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100 + Paging: not paging Requests: 0 + Use count: 1 +OpenBSC# subscriber imsi 262429876543210 authorized 1 <4> +OpenBSC# subscriber imsi 262429876543210 extension 23234242 <5> +OpenBSC# subscriber imsi 262429876543210 name Sub Scriber <6> +OpenBSC# show subscriber imsi 262429876543210 <7> + ID: 3, Authorized: 1 + Name: 'Sub Scriber' + Extension: 23234242 + LAC: 0/0x0 + IMSI: 262429876543210 + Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100 + Paging: not paging Requests: 0 + Use count: 1 +---- +<1> as you can see, a newly-created subscriber is not automatically authorized. + We will change this in the next step. +<2> the NITB has automatically allocated a random 5-digit extension (MSISDN) +<3> Location Area Code 0 means that this subscriber is currently not registered on the network +<4> Authorize the subscriber +<5> Change the extension (MSISDN) to 23234242 (optional) +<6> Give the subscriber a human-readable name (optional) +<7> Review the content of your new subscriber record + +NOTE: If you are running a network with A5 encryption enabled, you must also +configure the secret key (Ki) of the SIM card in the HLR. + +You can change further properties on your just-created subscriber as explained +in <<hlr-subscr-properties>>. + +==== Creating subscribers in the SQL database + +In most applications, the network operator issues his own SIM cards, and +the subscriber records corresponding to each SIM will be pre-provisioned by +direct insertion into the SQL database. This is performed long before the +SIM cards are issued towards the actual end-users. + +This can be done by a custom program, the SQL schema is visible from the +`.schema` command on the sqlite3 command-line program, and there are several +scripts included in the OpenBSC source code, written in both Python as well as +Perl language. + +In case you are obtaining a starter kit with pre-provisioned SIM cards from +sysmocom: They will ship with a HLR SQL database containing the subscriber +records. + +==== Provisioning SIM cards + +In most applications, the operator obtains pre-provisioned SIM cards from a SIM +card supplier. + +If you prefer to provision the SIM cards yourself, you can use the pySim +tool available from http://cgit.osmocom.org/cgit/pysim/. It has the +ability to append the newly-provisioned SIM cards to an existing HLR +database, please check its `--write-hlr` command line argument. + + +[[hlr-subscr-properties]] +=== Changing subscriber properties + +Once a subscriber exists in the HLR, his properties can be set +interactively from the VTY. Modifying subscriber properties requires +the VTY to be in the privileged (`enable`) mode. + +All commands are single-line commands and always start with identifying +the subscriber on which the operation shall be performed. Such +identification can be performed by + +* IMSI +* TMSI +* extension number +* ID (internal identifier) + + +==== Changing the subscriber phone number + + +You can set the phone number of the subscriber with IMSI 602022080345046 +to 12345 by issuing the following VTY command from the enable node: + +.Changing the phone number of a subscriber +---- +OpenBSC# subscriber imsi 602022080345046 extension 12345 +---- + + +==== Changing the subscriber name + +The subscriber name is an internal property of OsmoNITB. The name will +never be transmitted over the air interface or used by the GSM protocol. +The sole purpose of the name is to make log output more intuitive, as +human readers of log files tend to remember names easier than IMSIs or +phone numbers. + +In order to set the name of subscriber with extension number 12345 to +"Frank", you can issue the following command on the VTY enable node: +`subscriber extension 12345 name Frank` + +The name may contain spaces and special characters. You can verify the +modified subscriber record by issuing the `show subscriber extension +12345` command. + + +==== Changing the authorization status + +As the HLR automatically adds records for all subscribers it sees, those +that are actually permitted to use the network have to be authorized by +setting the authorized property of the subscriber. + +You can set the authorized property by issuing the following VTY command +from the enable node: + +.Authorizing a subscriber +---- +OpenBSC# subscriber extension 12345 authorized 1 +---- + +Similarly, you can remove the authorized status from +a subscriber by issuing the following command: + +.Un-authorizing a subscriber +---- +OpenBSC# subscriber extension 12345 authorized 0 +---- + + +==== Changing the GSM authentication algorithm and Ki + +In order to perform cryptographic authentication of the subscriber, his +Ki needs to be known to the HLR/AUC. Furthermore, the authentication +algorithm implemented on the SIM card (A3/A8) must match that of the +algorithm configured in the HLR. + +Currently, OsmoNITB supports the following authentication algorithms: + +none:: No authentication is performed +xor:: Authentication is performed using the XOR algorithm (for test/debugging purpose) +comp128v1:: Authentication is performed according to the COMP128v1 algorithm + +WARNING: None of the supported authentication algorithms are +cryptographically very strong. Development is proceeding to include +support for stronger algorithms like GSM-MILENAGE. Please contact +sysmocom if you require strong authentication support. + +In order to configure a subscriber for COMP128v1 and to set his Ki, you +can use the following VTY command from the enable node: + +.Configuring a subscriber for COMP128v1 and setting Ki +---- +OpenBSC# subscriber extension 2342 a3a8 comp128v1 000102030405060708090a0b0c0d0e0f +---- + diff --git a/manuals/OsmoNITB/chapters/net.adoc b/manuals/OsmoNITB/chapters/net.adoc new file mode 100644 index 000000000..455e1a6ab --- /dev/null +++ b/manuals/OsmoNITB/chapters/net.adoc @@ -0,0 +1,139 @@ +[[net]] +== OsmoNITB Core Network Subsystem + +The OsmoNITB Core Network is a minimalistic implementation of the +classic MSC/VLR/HLR/AUC/SMSC components. None of the standardized core +network protocols (such as SCCP/TCAP/MAP) are used, interfaces between +VLR and HLR are simple function calls inside the same software package. + +OsmoNITB can thus provide autonomous voice and SMS services to its +coverage area, but it cannot provide roaming interfaces to classic GSM +operators. To support this configuration, it is suggested to use the +OsmoBSC variant of OpenBSC and interface it with a conventional MSC +using A-over-IP protocol. + +If you have classic GSM network/operator background, many of the +concepts used in OsmoNITB will appear foreign to you, as they are very +unlike the conventional GSM networks that you have worked with. + + +=== Configuring the Core Network + +Like everything else, the core network related parameters are configured +using the VTY. The respective parameters are underneath the +`network` config node. + +You can get to that node by issuing the following commands: + +.Entering the config network node +---- +OpenBSC> enable +OpenBSC# configure terminal +OpenBSC(config)# network +OpenBSC(config-net)# +---- + +A full reference to them can be found in the _OsmoNITB VTY reference +manual_ <<vty-ref-osmonitb>>. This section will only introduce the most +commonly used settings in detail. + +[TIP] +==== +You can always use the `list` VTY command to get a list of all possible +commands at the current node. +==== + + +=== Configuring the MCC/MNC + +The key identities of every GSM PLMN is the MCC and MNC. 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, you may enter: + +.Configuring the MCC/MNC +---- +OpenBSC(config-net)# network country code 262 +OpenBSC(config-net)# 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. You can activate it, and set its +configuration using the VTY. An example is provided below. + +.Configuring MM INFO +---- +OpenBSC(config-net)# mm info 1 +OpenBSC(config-net)# short name OpenBSC +OpenBSC(config-net)# long name OpenBSC +---- + +[NOTE] +==== +Not all phone support the MM INFO procedure. Unless they already are +factory-programmed to contain the name for your MCC/MNC, then they will +likely only provide a numeric display of the network name, such as +__262-89__ or with 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 OsmoNITB is running. As BTSs attached +to one OsmoNITB can reside in different time zones, it is possible to +use the `timezone` command at each BTS node to set different time +zone offsets in hours and quarter hours. + + +=== Setting the NECI bit + +NECI (New Establishment Cause Indication) is an optional change of the +definition for establishment cause in the RACH burst. Among other +things, in a network with NECI, a MS can explicitly indicate its TCH/H +capability while asking for a dedicated radio channel. + +It is strongly recommended to use NECI. You can do so by issuing the following command: +.Enabling NECI +---- +OpenBSC(config-net)# neci 1 +---- + + +=== Configuring Handover + +As opposed to cell re-selection in idle mode, handover refers to the +explicit transfer of a MS dedicated channel from one radio channel to +another. This typically happens due to a MS moving from one cell to +another while in an active call. + +OsmoNITB has a number of hand-over related parameters by which the +hand-over algorithm can be tuned. Logically, those settings are settings +of the BSC component, but for historic reasons, they are also configured +under the __network__ VTY node. + +.Configuring Handover +---- +OpenBSC(config-net)# handover 1 +OpenBSC(config-net)# handover window rxlev averaging 10 +OpenBSC(config-net)# handover window rxqual averaging 1 +OpenBSC(config-net)# handover window rxlev neighbor averaging 10 +OpenBSC(config-net)# handover power budget interval 6 +OpenBSC(config-net)# handover power budget hysteresis 3 +OpenBSC(config-net)# handover maximum distance 9999 +---- + +[NOTE] +==== +If you are receiving the following error message: +---- +OpenBSC(config-net)# handover 1 +% Cannot enable handover unless RTP Proxy mode is enabled by using the -P command line option +---- +then you should do as indicated and make sure to start your `osmo-nitb` process using +the `-P` command line option. +==== diff --git a/manuals/OsmoNITB/chapters/overview.adoc b/manuals/OsmoNITB/chapters/overview.adoc new file mode 100644 index 000000000..d161af3f9 --- /dev/null +++ b/manuals/OsmoNITB/chapters/overview.adoc @@ -0,0 +1,196 @@ +[[overview]] +== Overview + +This manual should help you getting started with OsmoNITB. It will cover +aspects of configuring and running the OsmoNITB. + +[[intro_overview]] +=== About OsmoNITB + +OsmoNITB is one particular version of the OpenBSC software suite. +Unlike classic, distributed, hierarchical GSM networks, OsmoNITB +implements all parts of a GSM Network (BSC, MSC, VLR, HLR, AUC, SMSC) +__in the box__, i.e. in one element. + +The difference between classic GSM network architecture and the OsmoNITB +based GSM network architecture is illustrated in <<fig-gsm-classic>> and +<<fig-gsm-nitb>>. + +[[fig-gsm-classic]] +.Classic GSM network architecture (simplified) +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"] + MS1 [label="MS"] + MS2 [label="MS"] + MS3 [label="MS"] + BTS0 [label="BTS"] + BTS1 [label="BTS"] + MSC [label="MSC/VLR"] + HLR [label="HLR/AUC"] + MS0->BTS0 [label="Um"] + MS1->BTS0 [label="Um"] + MS2->BTS1 [label="Um"] + MS3->BTS1 [label="Um"] + BTS0->BSC [label="Abis"] + BTS1->BSC [label="Abis"] + BSC->MSC [label="A"] + MSC->HLR [label="C"] + MSC->EIR [label="F"] + MSC->SMSC +} +---- + +[[fig-gsm-nitb]] +.GSM system architecture using OsmoNITB +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"] + MS1 [label="MS"] + MS2 [label="MS"] + MS3 [label="MS"] + BTS0 [label="BTS"] + BTS1 [label="BTS"] + MS0->BTS0 [label="Um"] + MS1->BTS0 [label="Um"] + MS2->BTS1 [label="Um"] + MS3->BTS1 [label="Um"] + BTS0->BSC [label="Abis"] + BTS1->BSC [label="Abis"] + subgraph cluster_nitb { + label = "OsmoNITB"; + BSC + MSC [label="MSC/VLR"] + HLR [label="HLR/AUC"] + BSC->MSC [label="A"] + MSC->HLR [label="C"] + MSC->EIR [label="F"] + MSC->SMSC; + } +} +---- + + +=== Software Components + +OsmoNITB contains a variety of different software components, which +we'll quickly describe in this section. + +==== A-bis Implementation + +OsmoNITB implements the ETSI/3GPP specified A-bis interface, including +_3GPP TS 48.056_ <<3gpp-ts-48-056>> (LAPD), _3GPP TS 48.058_ +<<3gpp-ts-48-058>> (RSL) and 3GPP TS 52.021 <<3gpp-ts-52-021>> (OML). In +addition, it supports a variety of vendor-specific extensions and +dialects in order to communicate with BTSs from Siemens, Nokia, +Ericsson, ip.access and sysmocom. + +For more information, see <<bts>> and <<bts-examples>>. + + +==== BSC Implementation + +The BSC implementation covers the classic functionality of a GSM Base +Station Controller, i.e. + +* configuring and bringing up BTSs with their TRXs and TSs +* implementing the A-bis interface / protocols for signalling and actual + voice data (TRAU frames). +* processing measurement results from the mobile stations in dedicated + mode, performing hand-over decision and execution. +* Terminating the _3GPP TS 24.008_ <<3gpp-ts-24-008>> RR (Radio Resource) + sub-layer from the MS. + +For more information, see <<net>>, <<bts>> and <<bts-examples>>. + + +==== HLR/AUC + +A minimalistic implementation of the subscriber database (HLR) and +subscriber secret key storage (AUC). + +For more information, see <<hlr>>. + + +==== 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 of OsmoNITB implements the mobility management (MM) +functions of the TS 04.08, as well as the optional security related +procedures for cryptographic authentication and encryption. + +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>>. + + +==== TRAU mapper / E1 sub-channel muxer + +Unlike classic GSM networks, OsmoNITB does not perform any transcoding. +Rather, a compatible codec is selected for both legs of a call, and +codec frames are passed through transparently. In order to achieve this +with E1 based BTS, OsmoNITB contains a E1 sub-channel de- and +re-multiplexer as well as a TRAU mapper that can map uplink to downlink +frames and vice versa. + + +==== RTP proxy + +BTS models implementing A-bis over IP don't use classic TRAU frames but +typically transport the voice codec frames as RTP/UDP/IP protocol. +OsmoNITB can either instruct the BTSs to send those voice streams +directly to each other (BTS to BTS without any intermediary), or it can +run an internal RTP proxy for passing frames from one BTS to another. + +.RTP flow without RTP proxy mode (default) +[graphviz] +---- +digraph G { + rankdir=LR; + + MS0 [label="MS A"]; + MS1 [label="MS B"]; + BTS0 [label="BTS A"]; + BTS1 [label="BTS B"]; + NITB; + + MS0 -> BTS0; + MS1 -> BTS1; + BTS0 -> NITB [label="Abis OML+RSL",dir=both]; + BTS1 -> NITB [label="Abis OML+RSL",dir=both]; + BTS0 -> BTS1 [label="RTP",dir=both] +} +---- + +.RTP flow with RTP proxy mode +[graphviz] +---- +digraph G { + rankdir=LR; + + MS0 [label="MS A"]; + MS1 [label="MS B"]; + BTS0 [label="BTS A"]; + BTS1 [label="BTS B"]; + NITB; + + MS0 -> BTS0; + MS1 -> BTS1; + BTS0 -> NITB [label="Abis OML+RSL",dir=both]; + BTS1 -> NITB [label="Abis OML+RSL",dir=both]; + BTS0 -> NITB [label="RTP",dir=both] + BTS1 -> NITB [label="RTP",dir=both] +} +---- diff --git a/manuals/OsmoNITB/chapters/running.adoc b/manuals/OsmoNITB/chapters/running.adoc new file mode 100644 index 000000000..406c41c19 --- /dev/null +++ b/manuals/OsmoNITB/chapters/running.adoc @@ -0,0 +1,104 @@ +== Running OsmoNITB + +The OsmoNITB executable (`osmo-nitb`) offers the following command-line +arguments: + +=== SYNOPSIS + +*osmo-nitb* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'DATABASE'] [-a] [-P] [-m] [-C] [-r 'RFCTL'] + +=== 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 HLR/AUC + storage +*-a, --authorize-everyone*:: + Authorize every subscriber to the network. This corresponds to + the `auth-policy open` VTY configuration option. + + + WARNING:: This is dangerous as you may disrupt services to + subscribers that are not part of your network! Don't use unless + you absolutely know what you're doing! +*-P, --rtp-proxy*:: + Enable the RTP proxy code inside OsmoNITB. This will force all + voice RTP data to pass through OsmoNITB, rather than going + directly from BTS to MGW, or BTS to BTS. +*-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. +*-r, --rf-ctl 'RFCTL'*:: + Offer a Unix domain socket for RF control at the path/filename + 'RFCTL' in the file system. + + +=== Multiple instances + +Running multiple instances of `osmo-nitb` is possible if all interfaces (VTY, +OML) 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. + +The VTY and the control interface can be bound to IP addresses from the loopback +address range. + +.Example: Binding VTY and control interface to a specific ip-address +---- +line vty + bind 127.0.0.2 +ctrl + bind 127.0.0.2 +---- + +The OML interface also needs to be separated by binding it to different IP +addresses. Usually it is not possible to use addresses from the loopback +address range here since the OML interface needs to be reachable by an external +BTS. If only one ethernet interface is available, sub-devices with different IP +addresses can be created. + +.Example: Binding OML to a specific IP address +---- +e1_input + ipa bind 10.9.1.101 +---- + +NOTE: Depending on the application, it is necessary to have different ARFCN, +MCC, MNC and network name settings. It might also be necessary to point to +different database and config files using command line options (see option +-l and -c). + +NOTE: If an external MNCC handler is used, the user has to assign a different +socket path to reach osmo-nitb instance using commandline option -M. If option +-M is left out, the internal MNCC handler is used and no further configuration +is required |