Project

General

Profile

Osmocom Network In The Box » History » Version 87

neels, 11/24/2017 02:11 PM

1 23 neels
{{>toc}}
2
3 1 neels
h1. Osmocom Network In The Box
4
5 22 neels
This is a brief guide to the most basic and minimal setup of an Osmocom 2G and/or 3G network for voice and data services. It is a good starting point for newcomers to familiarize with the software, and to expand upon by the [[Osmocom Manuals]] and other wiki pages.
6 21 neels
7 68 neels
h1. OsmoNITB R.I.P., long live the Network In The Box
8 1 neels
9 2 neels
Historically, Osmocom offered the [[OsmoNITB:]] "Network-In-The-Box" as an actual single program. It was a useful simplification at the time, but in 2017, Osmocom have decided to split OsmoNITB into programs more closely resembling traditional network architecture. It is recommended to use the new separate components instead of the OsmoNITB, since active development focus has moved there.
10 1 neels
11 4 neels
It is still very much possible to run a complete Osmocom core network in one "box". For example, a sysmoBTS can run the entire core network on the same hardware that drives the TRX, making it a complete network in actually one single box. At the same time, having separate components also allows scaling to large deployments, with properly distributed load and a central subscriber database.
12 1 neels
13 2 neels
To migrate from OsmoNITB to the new separate programs, see the [[OsmoNITB Migration Guide]].
14
15 68 neels
h1. Part of this Complete Network
16 2 neels
17 32 neels
Assuming that you have your radio hardware ready (a BTS, a femto cell or an SDR driven by osmo-trx), the core network consists of separate programs providing voice/SMS/USSD ("circuit-switched" or CS) and data ("packet-switched" or PS) services.
18 2 neels
19 32 neels
Here is a table of the components you need:
20 1 neels
21 32 neels
|\4. *Required for*  |/3. *Program* |/3. *Description* |
22
|\2. *2G*  |\2. *3G* |
23
| *CS* | *PS* | *CS* | *PS* |
24
| ✔ | ✔ | ✔ | ✔ | [[OsmoHLR:]] | Home Location Register, stores subscriber IMSI, phone number and auth tokens. |
25
| ✔ | (1) | ✔ | (1) | [[OsmoMSC:]] | Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). |
26
| ✔ |   | ✔ |   | [[OsmoMGW:]] | Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. |
27
| ✔ | ✔ | ✔ | ✔ | [[OsmoSTP:]] | Signal Transfer Point, routes SCCP messages between MSC, BSC, HNBGW and for 3G also the SGSN. |
28
| ✔ | (1) |   |   | [[OsmoBSC:]] | 2G Base Station Controller, manages logical channels and other lower level aspects for one or more 2G BTS; it is technically part of the BSS and not the "core network". |
29
|   |   | ✔ | ✔ | [[OsmoHNBGW:]] | 3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell and forwards to MSC and SGSN by SCCP/M3UA via OsmoSTP. |
30
|   | ✔ (2) |   | ✔ (2) | [[OpenGGSN:|OsmoGGSN]] | Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink. |
31
|   | ✔ |   | ✔ | [[OsmoSGSN:]] | Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts. |
32
| ✔ | (1) |   |   | [[OsmoBTS:]] | for 2G networks, drives the TRX and ties to the BSC via Abis-interface. |
33
|   | ✔ |   |   | [[OsmoPCU:]] | for 2G networks, a component closely tied to the BTS, drives the TRX for PS timeslots and ties to the SGSN via Gb-interface. |
34 37 neels
|   |   | ✔ | ✔ | hNodeb | 3rd party 3G femto cell hardware to connect to OsmoHNBGW via Iuh |
35 5 neels
36 32 neels
1: PS is always an _addition_ to CS: even though these components do not handle PS requests, you need to have these to be able to setup and register with a network, which is a prerequisite for data services.
37 28 neels
38 74 neels
2: For the GGSN to successfully route packets to an internet uplink, it needs a tun device set up and usually IP masquerading/forwarding enabled. Please refer to the OsmoGGSN manual for more details.
39 18 neels
40 68 neels
h2. Topology
41 55 neels
42
{{graphviz_link()
43
digraph G {
44
  rankdir = LR;
45 56 neels
  
46
  MS [label="MS\n(2G phone)"]
47
  UE [label="UE\n(3G phone)"]
48 1 neels
49 56 neels
  subgraph cluster_bts {
50
    BTS [rank="min"]
51
    PCU [rank="min"]
52
  }
53
54
  subgraph cluster_msc_mgw {
55 59 neels
    label=MGCP;style=dotted
56 56 neels
    MSC
57 57 neels
    MGW1 [label="MGW"]
58 56 neels
  }
59
60
  subgraph cluster_bsc_mgw {
61 59 neels
    label=MGCP;style=dotted
62 56 neels
    BSC
63 57 neels
    MGW2 [label="MGW"]
64 1 neels
  }
65
66 59 neels
  hNodeB [shape="box",label="hNodeB\n(3G femto cell)"]
67
68 61 neels
  MS -> BTS [label="Um"]
69 65 neels
  MS -> PCU [style="dashed"]
70 60 neels
 
71 56 neels
  BTS -> BSC [label="Abis/IP"]
72
  STP [label="STP\n(SCCP/M3UA)"]
73
  BSC -> STP -> MSC [label="A"]
74 70 neels
  MSC -> HLR [label="GSUP"]
75
  SGSN -> HLR [label="GSUP",style="dashed"]
76 62 neels
  UE -> hNodeB [label="Uu"]
77 65 neels
  UE -> hNodeB [style="dashed"]
78 56 neels
  hNodeB -> HNBGW [label="Iuh"]
79
  HNBGW -> STP -> MSC [label="IuCS"]
80 58 neels
  HNBGW -> STP -> SGSN [label="IuPS",style="dashed"]
81 61 neels
  PCU -> SGSN [label="Gb",style="dashed"]
82 58 neels
  SGSN -> GGSN [label="GTP-C",style="dashed"]
83
  SGSN -> GGSN [label="GTP-U(2G)",style="dashed"]
84
  hNodeB -> GGSN [label="GTP-U(3G)",style="dashed"]
85
  GGSN -> internet [label="tun",style="dashed"]
86 56 neels
87 73 neels
  BTS -> MGW2 -> MGW1 [label="RTP"]
88 59 neels
  MGW1 -> MGW1 [label="RTP"]
89 1 neels
  hNodeB -> MGW1 [label="IuUP/RTP"]
90 59 neels
91
  A, B, C, D [style="invisible"]
92 63 neels
  A -> B [label="data (PS)",style="dashed"]
93
  C -> D [label="voice (CS)"]
94 56 neels
95 55 neels
}
96
}}
97
98 5 neels
h1. Have to Know
99 10 neels
100
Each program features a detailed [[Osmocom Manuals|user manual]], your primary source of information to expand on the setup described here.
101 24 laforge
102 5 neels
Osmocom offers [[Binary_Packages|compiled packages for various distributions]]. If you're up to it, you may also [[Build from Source]].
103
104
Each Osmocom program typically has
105
106 1 neels
* a distinct configuration file;
107 25 neels
* a VTY telnet console for live interaction;
108 1 neels
* a CTRL interface for live interaction from 3rd party programs.
109 18 neels
110
See [[Port Numbers]] to find out which program runs VTY on which port.
111
112
h1. Configuration Examples
113 5 neels
114 83 neels
Here is a tarball of the config files discussed below: attachment:nitb.tar
115
116 6 neels
h2. OsmoHLR
117
118 67 neels
Home Location Register, stores subscriber IMSI, phone number and auth tokens. This is where you configure who is allowed on your network and who has which phone number.
119
120 72 neels
osmo-hlr will automatically bootstrap an empty subscriber database. See the [[Osmocom Manuals|manual]] on how to add one or more subscribers -- if you don't know your IMSI, it can be useful to attempt a connection and watch the OsmoHLR log for a rejected IMSI. To migrate subscribers from an older OsmoNITB database, see the [[OsmoNITB migration guide]].
121 6 neels
122 50 neels
While you do need one, your configuration file may actually remain empty. This will serve GSUP on localhost (127.0.0.1), sufficient for a Network In The Box with MSC and SGSN on the same machine as the HLR.
123 6 neels
124 48 neels
*osmo-hlr.cfg*
125
<pre>
126 71 neels
# empty, the defaults are sufficient
127 48 neels
</pre>
128
129 6 neels
h2. OsmoMSC
130 1 neels
131 67 neels
Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). The OsmoMSC is your central "manager" of the network.
132 66 neels
133 6 neels
The VLR component of OsmoMSC needs to connect to the OsmoHLR's GSUP server to know which subscribers are authorized. By default, it will connect to OsmoHLR on localhost, no explicit config needed.
134 26 neels
135 6 neels
To be reachable by OsmoBSC and OsmoHNBGW, OsmoMSC needs an SCCP point code, and it needs to connect to OsmoSTP to make itself known to SCCP routing.
136 7 neels
137 86 neels
* There is a default point code, currently 0.23.1 (in 8.8.3 point code format, see [[Point Codes]]).
138 6 neels
* OsmoMSC will by default look for OsmoSTP on localhost's M3UA port, 2905.
139 7 neels
140 51 neels
To direct RTP streams, OsmoMSC needs an OsmoMGW instance (see OsmoMGW below).
141 38 neels
142 51 neels
You only need to set up your MCC, MNC, and how to reach/use the MGW.
143 43 neels
144 49 neels
*osmo-msc.cfg*
145 1 neels
<pre>
146 38 neels
network
147
 network country code 901
148 53 neels
 mobile network code 70
149
msc
150 82 neels
 mgw remote-ip 192.168.0.9
151 45 neels
 mgw endpoint-range 1 32
152 38 neels
</pre>
153 47 neels
154 1 neels
h2. OsmoMGW
155
156 67 neels
Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. The Media Gateway receives instructions in the form of MGCP messages from OsmoMSC/OsmoBSC. It forwards RTP streams directly between BTS, femto cells and remote endpoints, e.g. other MGW instances, and its job is to transcode between codecs (future).
157 52 neels
158 47 neels
You need an OsmoMGW to serve OsmoMSC's MGCP requests, and an OsmoMGW to serve OsmoBSC's MGCP requests. In fact, these two can be served by one single OsmoMGW instance. If you would like to keep two separate OsmoMGW instances, you need to take care that they don't attempt to bind to identical ports on the same IP address (for MGCP, but also for VTY and CTRL interfaces).
159
160
Consider that you have a 2G network with an external BTS (say a sysmoBTS), which means that you need your OsmoBSC's MGW instance to be reachable on a public interface. So far the MSC's MGW can be on a local loopback interface, it only needs to be reachable by the BSC's MGW and by the MSC.
161
162
If you also have a 3G femto cell, then the MSC's MGW instance also needs to be on a public interface. At this point you either need two public interface addresses, or you need to put one of the MGWs on a different MGCP port.
163
164
If you use one OsmoMGW for both BSC and MSC, there are no port conflicts, but you need to take care that MSC and BSC use differing endpoint identifiers, or they will interfere with each others' RTP stream configurations.
165
166
To increase the likelihood that your first setup will work out, below examples pick distinct endpoint ranges so that MSC and BSC could use the same MGW instance, while at the same time provide config files that allow running two MGWs on the same public IP address.
167
168
h3. OsmoMGW for OsmoMSC
169 1 neels
170 9 neels
*NOTE: Currently, OsmoMSC still requires the legacy osmo-bsc_mgcp program, which will move to the new osmo-mgw soon. osmo-bsc_mgcp is still available from osmo-mgw.git. For osmo-bsc_mgcp, you can use the identical config as shown for the MSC's MGW here.*
171 47 neels
172 1 neels
* In a setup that truly runs in one box (e.g. sysmoBTS or osmo-trx with co-located core network), this may be localhost (127.0.0.1), which is the default, and your config file may omit the 'bind ip'.
173 9 neels
* With a separate BTS and/or RNC (e.g. 3G femto cell or nanoBTS), make sure to configure an IP address that is reachable by the hNodeB and BTS:
174 1 neels
175
*osmo-mgw-for-msc.cfg*
176 9 neels
<pre>
177 48 neels
mgcp
178 82 neels
 bind ip 192.168.0.9
179 40 neels
 number endpoints 64
180 82 neels
line vty
181
 bind 127.0.0.1
182 1 neels
</pre>
183
184 47 neels
h3. OsmoMGW for OsmoBSC
185 1 neels
186
OsmoBSC also requires an OsmoMGW instance to run alongside it. In a setup where OsmoBSC and OsmoMGW run on the same box, they may in fact share the same OsmoMGW instance, as long as BSC and MSC use different endpoint identifiers.
187
188 47 neels
It is semantically more clear to run a separate OsmoMGW instance for the OsmoBSC, which then needs to not interfere with the other MGW's ports, for example:
189 1 neels
190
*osmo-mgw-for-bsc.cfg*
191
<pre>
192 40 neels
mgcp
193 82 neels
 bind ip 192.168.0.9
194
 # default port is 2427 (is used for MSC's MGW)
195 47 neels
 bind port 12427
196
 number endpoints 64
197 41 neels
line vty
198 82 neels
 # default VTY interface is on 127.0.0.1 (used for MSC's MGW)
199 41 neels
 bind 127.0.0.2
200 40 neels
</pre>
201
202 9 neels
Note that osmo-bsc.cfg below sets the 'mgw remote-port' to the 'bind port' configured here (the method to run two MGW on the same public IP address), and picks a different 'mgw endpoint' range than the OsmoMSC (the method to use the same MGW for both BSC and MSC) -- these are two separate, redundant measures, and you usually would pick only one of them.
203 1 neels
204 9 neels
h2. OsmoSTP
205
206 67 neels
Signal Transfer Point, acts as a server for routing SCCP messages. OsmoMSC, OsmoBSC, OsmoHNBGW and OsmoSGSN contact OsmoSTP and announce their own point code, after which they may instruct OsmoSTP to route SCCP messages to each other by these point codes.
207 9 neels
208
The basic configuration that permits dynamic routing is:
209
210
*osmo-stp.cfg*
211
<pre>
212
cs7 instance 0
213
 xua rkm routing-key-allocation dynamic-permitted
214
 listen m3ua 2905
215 11 neels
  accept-asp-connections dynamic-permitted
216
</pre>
217 1 neels
218
h2. OsmoBSC
219 11 neels
220 67 neels
2G Base Station Controller, manages logical channels and other lower level aspects for one or more 2G BTS. The BSC tells the MSC what the phones would like to do, and in turn the MSC tells the BSC to establish channels, page phones, and take care of the lower level BTS maintenance.
221
222 87 neels
OsmoBSC needs to register with OsmoSTP, and contact the MSC by its point code. If not configured otherwise, it will use OsmoMSC's default point code to contact it, see [[Point Codes]].
223 11 neels
224 48 neels
OsmoBSC needs to contact an OsmoMGW to direct RTP streams between BTS and the MSC's MGW, as discussed above under "OsmoMGW".
225 42 neels
226 11 neels
OsmoBSC also needs complete configuration of all connected BTS. This example shows configuration for a sysmoBTS.
227 15 neels
228
Furthermore, some network properties need to be set.
229 1 neels
230 83 neels
The 'gprs mode' determines whether packet switched access will be enabled. 'gprs mode none' switches off data services, it tells osmo-bts not to contact osmo-pcu to establish data service.
231 15 neels
232 83 neels
To allow data service, set a 'gprs mode gprs' or 'gprs mode egprs', and configure PDCH timeslots. Traditionally, a fixed amount of TCH timeslots for voice and PDCH timeslots for data service are configured. OsmoBTS also supports two types of dynamic timeslots, as described in the "Abis manual":http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf, chapter "Dynamic Channel Combinations". The following is a configuration with voice-and-data service based on Osmocom style dynamic timeslots:
233 15 neels
234 43 neels
*osmo-bsc.cfg* for voice and data service
235 48 neels
<pre>
236 75 neels
network
237
 network country code 901
238 1 neels
 mobile network code 70
239 75 neels
 mm info 1
240
 short name OsmoBSC
241
 long name OsmoBSC
242
 bts 0
243
  type sysmobts
244
  band GSM-1800
245
  location_area_code 23
246
  ip.access unit_id 1800 0
247
  gprs mode gprs
248 82 neels
  gprs nsvc 0 remote ip 192.168.0.9
249 75 neels
  gprs nsvc 0 remote udp port 23000
250
  gprs nsvc 0 local udp port 23000
251
  gprs nsvc 0 nsvci 1800
252
  gprs nsei 1800
253
  gprs cell bvci 1800
254
  trx 0
255
   rf_locked 0
256
   arfcn 868
257
   nominal power 23
258
   timeslot 0
259
    phys_chan_config CCCH+SDCCH4
260
   timeslot 1
261
    phys_chan_config SDCCH8
262
   timeslot 2
263
    phys_chan_config TCH/F_TCH/H_PDCH
264
   timeslot 3
265 1 neels
    phys_chan_config TCH/F_TCH/H_PDCH
266 75 neels
   timeslot 4
267
    phys_chan_config TCH/F_TCH/H_PDCH
268
   timeslot 5
269
    phys_chan_config TCH/F_TCH/H_PDCH
270
   timeslot 6
271
    phys_chan_config TCH/F_TCH/H_PDCH
272
   timeslot 7
273
    phys_chan_config PDCH
274
e1_input
275 1 neels
 e1_line 0 driver ipa
276 75 neels
msc 0
277 82 neels
 mgw remote-ip 192.168.0.9
278 75 neels
 mgw remote-port 12427
279
 mgw endpoint-range 33 64
280 1 neels
 allow-emergency deny
281
 codec-list hr3
282
</pre>
283
284
h2. OsmoHNBGW
285
286
3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell, separates it into IuCS and IuPS and forwards to the MSC and SGSN.
287
288 82 neels
OsmoHNBGW needs to connect to OsmoSTP for routing, and needs to know the MSC and SGSN point codes. If omitted, it assumes OsmoSTP on 127.0.0.1 and uses the point codes that are default in OsmoMSC and OsmoSGSN.
289 1 neels
290
It must also be reachable by the hNodeB, hence its Iuh must typically run on a public IP, not a loopback address like 127.0.0.1.
291
292 16 neels
*osmo-hnbgw.cfg*
293 1 neels
<pre>
294 82 neels
hnbgw
295
 iuh
296
  local-ip 192.168.0.9
297
</pre>
298
299
Note, until https://gerrit.osmocom.org/4977 is merged, you need to provide the point-codes explicitly, like:
300
301
<pre>
302 12 neels
cs7 instance 0
303 82 neels
 point-code 0.0.3
304 12 neels
 ! Address book entries, used below
305 1 neels
 sccp-address msc
306
  point-code 0.23.1
307
 sccp-address sgsn
308 82 neels
  point-code 0.0.2
309 1 neels
hnbgw
310
 iuh
311 82 neels
  local-ip 192.168.0.9
312 1 neels
 iucs
313 12 neels
  remote-addr msc
314 1 neels
 iups
315
  remote-addr sgsn
316
</pre>
317
318
h2. OsmoGGSN
319
320
Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink. To provide packet switched service, OsmoGGSN must offer GTP service to the OsmoSGSN.
321
322 82 neels
Notably, both OsmoGGSN and OsmoSGSN must use identical port numbers, which is an intrinsic requirement of the GTP protocol. Hence they must not run on the same IP address. Furthermore, for 2G networks, the SGSN must be reachable by the PCU and thus needs to be on a public interface if the BTS is a separate box; for 3G networks, the GGSN must be reachable by the hNodeB and thus needs to be on a public interface. So, to cover both, you need to have *two* public interfaces; this example uses 192.168.0.42, made available by
323 12 neels
324 82 neels
<pre>
325
sudo ip addr add 192.168.0.42/32 dev eth0
326
</pre>
327
328
This is of course blatantly ignoring the local DHCP server's authority, just a quick hack.
329
330 1 neels
OsmoGGSN maintains a gsn_restart counter, to be able to reliably communicate to the SGSN that it has restarted. This is kept in the 'state-dir', by default in /tmp.
331 13 neels
332 82 neels
It also needs access to a tun device with an address range available to subscribers' PDP contexts. This may be configured ahead of time, so that OsmoGGSN does not need root privileges. If run with 'sudo', OsmoGGSN may also create its own tun device. In below example, the 'apn0' device has been created ahead of time, with:
333 13 neels
334 82 neels
<pre>
335
sudo ip tuntap add dev apn0 mode tun user $USER group $USER
336
sudo ip addr add 192.168.42.0/24 dev apn0
337
sudo ip link set apn0 up
338
</pre>
339
340
IPv4 operation is enabled by default, but for future compatibility, it is good to indicate that explicitly.
341
342 76 neels
OsmoGGSN furthermore indicates DNS servers, as well as an IPv4 address range to assign to subscribers' PDP contexts.
343 13 neels
344 85 neels
Note that the APN named in this config file (here "internet") needs to be configured on your phone, see [[Osmocom Network In The Box#APN-for-Data-Service|APN for Data Service]] below. With the @default-apn@ command, any unknown APN name will use that default APN instead, but still you usually have to define _some_ APN on your phone so that it even tries to connect to the data service.
345 13 neels
346 85 neels
A profound part of GGSN configuration is the network setup of your system: you need to allow the packets to be routed between the subscribers and your internet uplink. See the [[Osmocom Manuals|OsmoGGSN User Manual]], section _Running OsmoGGSN_ / _Routing_.
347 84 neels
348 13 neels
*osmo-ggsn.cfg*
349
NOTE: this configuration requires running osmo-ggsn with root privileges, as well as IP-forwarding and masquerading to be enabled
350
<pre>
351
ggsn ggsn0
352 82 neels
 gtp bind-ip 192.168.0.42
353 76 neels
 apn internet
354 82 neels
  tun-device apn0
355 1 neels
  type-support v4
356
  ip dns 0 192.168.0.1
357 76 neels
  ip dns 1 8.8.8.8
358
  ip prefix dynamic 192.168.42.0/24
359 82 neels
  no shutdown
360
 default-apn internet
361 14 neels
 no shutdown ggsn
362
</pre>
363 67 neels
364
h2. OsmoSGSN
365 14 neels
366
Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts for data services.
367
368
OsmoSGSN needs to reach the GGSN to establish GTP tunnels for subscribers. It must have a separate GTP IP address from OsmoGGSN, as mentioned before.
369
370
For 2G, OsmoSGSN needs to be reachable by the PCU, and needs a public IP for the Gb interface if it is not running directly on the BTS hardware (e.g. on sysmoBTS or when using osmo-trx). For 2G operation, SGSN and GGSN may both use a local IP address for GTP, as long as they differ (e.g. 127.0.0.1 and 127.0.0.2).
371
372
For 3G, OsmoSGSN needs to be reachable by both the HNBGW for IuPS as well as by the hNodeB for GTP, i.e. it definitely needs to have a public IP address for the GTP port. IuPS may remain local if both HNBGW and SGSN are on the same box.
373
374 1 neels
Finally, OsmoSGSN needs access to OsmoHLR to access subscriber data. Set 'auth-policy remote' to use the HLR for subscriber authorization. The default 
375
376
*osmo-sgsn.cfg*
377 14 neels
<pre>
378 77 neels
sgsn
379 82 neels
 gtp local-ip 192.168.0.9
380
 ggsn 0 remote-ip 192.168.0.42
381 79 neels
 ggsn 0 gtp-version 1
382 14 neels
 auth-policy remote
383 77 neels
 gsup remote-ip 127.0.0.1
384
ns
385 82 neels
 encapsulation udp local-ip 192.168.0.9
386 1 neels
 encapsulation udp local-port 23000
387
 encapsulation framerelay-gre enabled 0
388 80 neels
</pre>
389 81 neels
390 18 neels
The @auth-policy remote@ requires that you have the SIM cards' authentication tokens in your OsmoHLR database. Instead, you can use @auth-policy accept-all@, but be aware that this will only work for 2G. 3G networks _require_ successful authentication, and @auth-policy remote@ is your _only_ option for a 3G SGSN.
391 17 neels
392
h1. Running Examples
393
394
Each Osmocom program comes with a systemd service file. It is recommended to place config files in /etc/osmocom/ and launch the individual components using systemd.
395
396
When installed from debian or opkg feeds, you will find the systemd service files in /lib/systemd/system/.
397
398
Re/starting and stopping then works like this:
399
400
<pre>
401 1 neels
systemctl restart osmo-hlr
402
systemctl stop osmo-hlr
403
</pre>
404 36 neels
405
It can be useful to have an @osmo-all@ script to re/start or stop all components at once, edit to pick yours:
406
407
*osmo-all* script
408
<pre>
409
#!/bin/sh
410
cmd="${1:-start}"
411
set -ex
412
systemctl $cmd osmo-hlr osmo-msc osmo-mgw osmo-ggsn osmo-sgsn osmo-stp osmo-bsc osmo-hnbgw osmo-bts-sysmo osmo-pcu 
413
</pre>
414
415
which allows
416
417
<pre>
418 1 neels
./osmo-all restart
419
./osmo-all status
420 36 neels
./osmo-all stop
421
</pre>
422
423 1 neels
For illustration, the manual command invocations for the components would look like this:
424
425
<pre>
426
osmo-hlr -l hlr.db -c osmo-hlr.cfg
427
osmo-msc -c osmo-msc.cfg
428
osmo-mgw -c osmo-mgw-for-msc.cfg
429
osmo-mgw -c osmo-mgw-for-bsc.cfg
430 48 neels
osmo-ggsn -c osmo-ggsn.cfg
431
osmo-sgsn -c osmo-sgsn.cfg
432 36 neels
osmo-stp -c osmo-stp.cfg
433 1 neels
osmo-bsc -c osmo-bsc.cfg
434
osmo-hnbgw -c osmo-hnbgw.cfg
435
# on a 2G sysmoBTS:
436 36 neels
osmo-bts-sysmo -c osmo-bts.cfg -s -M
437
osmo-pcu -c osmo-pcu.cfg
438
</pre>
439 18 neels
440
h1. Logging Examples
441
442
Osmocom programs have a common logging mechanism, configurable by the config files as well as the telnet VTY.
443
444 82 neels
h2. System Logging
445
446 18 neels
Depending on the system's logging configuration, logs may by default be visible in /var/log/daemon.log, or by using journalctl:
447
448 1 neels
<pre>
449
journalctl -f -u osmo-hlr
450
</pre>
451
452
When journalctl is used, it may be necessary to enable it first, e.g. by setting "Storage=volatile" in /etc/systemd/journald.conf followed by a 'systemctl restart systemd-journald'; you may also need to 'systemctl unmask systemd-journald.service systemd-jounald.socket'. Logging will only start appearing for components that were restarted after these changes.
453
454 82 neels
h2. telnet VTY logging
455
456 1 neels
A sure way to see the logs is to connect to the program's telnet VTY and enable logging on the VTY session -- this way you do not modify the application's default logging, but create a separate logging target for your telnet VTY session:
457
458
<pre>
459
$ telnet localhost 4254
460
OsmoMSC> logging enable 
461
OsmoMSC> logging level ?
462
  all      Global setting for all subsystems
463
  rll      A-bis Radio Link Layer (RLL)
464 18 neels
  cc       Layer3 Call Control (CC)
465
  mm       Layer3 Mobility Management (MM)
466
  [...]
467 35 neels
OsmoMSC> logging level all ?
468 19 neels
everything debug      info       notice     error      fatal      
469
OsmoMSC> logging level all debug 
470
OsmoMSC> logging filter all 1
471
</pre>
472
473
You will see logging output on your telnet console immediately. Note that the VTY prompt is still listening, so you may at any time issue 'logging filter all 0' to switch off logging, and be able to type commands without being cluttered by ongoing log output.
474 82 neels
475
h2. stderr logging
476
477
A common configuration you can add to any of the above configuration files to show *all* logging on stderr is:
478
479
<pre>
480
log stderr
481
 logging filter all 1
482
 logging color 1
483
 logging print category 1
484
 logging timestamp 1
485
 logging print extended-timestamp 1
486
 logging level all debug
487
</pre>
488
489
The @filter all 1@ switches on logging, read "do not discard all logging". The amount of logging seen is determined by @logging level ...@ commands, here all categories are set to level @debug@, to show absolutely all logging. You will probably want to refine that.
490 76 neels
491
h1. Troubleshooting
492
493
h2. APN for Data Service
494
495
For the data service to work, phones generally need an APN added to their
496
configuration, or they will not even attempt to establish a data connection.
497
The APN should match the name configured in osmo-ggsn.conf.
498
499
The APN configuration steps are usually similar to:
500
501
* Navigate to APN settings:
502
** 'Settings'
503
** 'Wireless & Networks'
504
** 'Mobile networks'
505
** 'Access Point Names'
506
* You should see the list of APNs (possibly empty)
507
* Press the Menu button
508
* Choose 'New APN'
509
* Enter values for 'Name' as well as 'APN'
510
* Again press the Menu button
511
* Choose 'Save'
512
* The APN should now appear in the list of APNs.
513 1 neels
* Possibly tap the bullet icon to select the APN as default.
Add picture from clipboard (Maximum size: 48.8 MB)