doc/sgsnemu.8

   1
   2 .\" * OpenGGSN - Gateway GPRS Support Node
   3 .\" * Copyright (C) 2002, 2003 Mondru AB.
   4 .\" *
   5 .\" * The contents of this file may be used under the terms of the GNU
   6 .\" * General Public License Version 2, provided that the above copyright
   7 .\" * notice and this permission notice is included in all copies or
   8 .\" * substantial portions of the software.
   9 .\" *
  10 .\" * The initial developer of the original code is
  11 .\" * Jens Jakobsen <jj@openggsn.org>
  12 .\" *
  13 .\" * Contributor(s):
  14 .\" *
  15 .\" Manual page for ggsn
  16 .\" SH section heading
  17 .\" SS subsection heading
  18 .\" LP paragraph
  19 .\" IP indented paragraph
  20 .\" TP hanging label
  21
  22 .TH sgsnemu 8 "May 2004"
  23 .SH NAME
  24 sgsnemu \- Serving GPRS Support Node Emulator
  25 .SH SYNOPSIS
  26 .B sgsnemu
  27 \-\-help
  28
  29 .B sgsnemu
  30 \-\-version
  31
  32 .B sgsnemu
  33 [
  34 .BI \-\-debug
  35 ] [
  36 .BI \-\-conf " file"
  37 ] [
  38 .BI \-\-pidfile " file"
  39 ] [
  40 .BI \-\-statedir " file"
  41 ] [
  42 .BI \-\-dns " host"
  43 ] [
  44 .BI \-\-listen " host"
  45 ] [
  46 .BI \-\-remote " host"
  47 ] [
  48 .BI \-\-contexts " num"
  49 ] [
  50 .BI \-\-timelimit " seconds"
  51 ] [
  52 .BI \-\-gtpversion " version"
  53 ] [
  54 .BI \-\-apn " apn"
  55 ] [
  56 .BI \-\-selmode " selmode"
  57 ] [
  58 .BI \-\-imsi " imsi"
  59 ] [
  60 .BI \-\-nsapi " nsapi"
  61 ] [
  62 .BI \-\-msisdn " msisdn"
  63 ] [
  64 .BI \-\-qos " qos"
  65 ] [
  66 .BI \-\-charging " charging"
  67 ] [
  68 .BI \-\-uid " uid"
  69 ] [
  70 .BI \-\-pwd " pwd"
  71 ] [
  72 .BI \-\-createif
  73 ] [
  74 .BI \-\-net " net"
  75 ] [
  76 .BI \-\-defaultroute
  77 ] [
  78 .BI \-\-ipup " script"
  79 ] [
  80 .BI \-\-ipdown " script"
  81 ] [
  82 .BI \-\-pinghost " host"
  83 ] [
  84 .BI \-\-pingrate " num"
  85 ] [
  86 .BI \-\-pingsize " num"
  87 ] [
  88 .BI \-\-pingcount " num"
  89 ]
  90 .SH DESCRIPTION
  91 .B sgsnemu
  92 is part of the
  93 .B OpenGGSN
  94 project, and implements a Serving GPRS Support Node (SGSN)
  95 emulator. It can be used for testing Gateway GPRS Support Nodes
  96 (GGSNs), GPRS core networks as well as GPRS roaming connections.
  97
  98 The GPRS functionality and protocols has been standardised by the
  99 Third Generation Partnership Project (3GPP). According to the 3GPP
 100 specifications an SGSN has several interfaces.
 101 .B sgsnemu
 102 implements the Gn/Gp interface which is used towards GGSNs.
 103
 104 The Gn/Gp interface can be seen as the uplink interface of the
 105 SGSN. It is used for communicating with a GGSN which is typically
 106 connected to the Internet. The Gn/Gp interface uses the GPRS tunneling
 107 protocol (GTP). User data packets (typically IP packets) are tunneled
 108 over GTP, which again uses UDP over IP.
 109
 110
 111 .B sgsnemu
 112 will establish a number of connections to the GGSN. An internal ping
 113 facility will transmit ping requests through the established
 114 connections. Alternatively a local network interface can be
 115 created. In this case
 116 .B sgsnemu
 117 will forward packets between the local network interface and the
 118 established connections on the Gn/Gp interface.
 119
 120 .B sgsnemu
 121 uses the
 122 .B TUN/TAP driver
 123 for the local interface. A tun network interface is established for
 124 each connection established to the GGSN.
 125
 126 Runtime errors are reported using the Osmocom logging framework.
 127
 128
 129 .SH OPTIONS
 130 .TP
 131 .BI --help
 132 Print help and exit.
 133
 134 .TP
 135 .BI --version
 136 Print version and exit.
 137
 138 .TP
 139 .BI --debug
 140 Run in debug mode (default = off)
 141
 142 .TP
 143 .BI --conf " file"
 144 Read configuration
 145 .I file
 146 where each line corresponds to one command line option, but with the
 147 leading '--' removed. Command line options override the options given
 148 in the configuration file.
 149
 150 .TP
 151 .BI --pidfile " file"
 152 Filename of process id
 153 .I file
 154 (default = ./sgsnemu.pid)
 155
 156 .TP
 157 .BI --statedir " path"
 158 .I path
 159 to directory of nonvolatile data (default = ./)
 160
 161 .TP
 162 .BI --dns " host"
 163 DNS server to use for APN lookups. If omitted the default system DNS
 164 configuration will be used.
 165
 166 .TP
 167 .BI --listen " host"
 168 Local interface IP address to use for the Gn/Gp interface. If omitted
 169 .B sgsnemu
 170 will listen to any IP address.
 171
 172 .TP
 173 .BI --remote " host"
 174 GGSN
 175 .I host
 176 to connect to. If DNS is setup correctly it should be possible to
 177 specify the access point name (APN) as the remote host.
 178
 179 .TP
 180 .BI --contexts " num"
 181 Number of contexts to establish. (default = 1). For multiple contexts
 182 the the first context is established using imsi + 0 and msisdn +
 183 0. The second context is established using imsi + 1 and msisdn +
 184 1. The third....
 185
 186 .TP
 187 .BI --timelimit " seconds"
 188 Exit
 189 .B sgsnemu
 190 after
 191 .I seconds.
 192 When using the ping facility
 193 .B sgsnemu
 194 will also exit after
 195 .B --pingcount
 196 packets has been transmitted.
 197
 198 .TP
 199 .BI --gtpversion " version"
 200 .I version
 201 of GTP to use when establishing a context (default = 1). If not able
 202 to establish a GTPv1 context sgsnemu will fall back to using GTPv0.
 203
 204 .TP
 205 .BI --apn " apn"
 206 .I apn
 207 to use when connecting to the GGSN (default = internet). APN is an
 208 abbreviation of Access Point Name.
 209
 210 .TP
 211 .BI --selmode " selmode"
 212 Selection mode to use when connecting to the GGSN (default =
 213 0x01). The encoding of the selection mode is as follows: 0: MS or
 214 network provided APN, subscribed verified, 1: MS provided APN,
 215 subscription not verified, 2: Network provided APN, subscription not
 216 verified.
 217
 218
 219 .TP
 220 .BI --imsi " imsi"
 221 .I imsi
 222 to use when connecting to the GGSN (default = 240010123456789). IMSI
 223 is an abbreviation of International Mobile Subscriber Identity. Must
 224 be exactly 15 digits. See the
 225 .I contexts
 226 option for the the use of the
 227 .I imsi
 228 option with multiple contexts.
 229
 230 .TP
 231 .BI --nsapi " nsapi"
 232 .I nsapi
 233 to use when connecting to the GGSN (default = 0). Must be between 0
 234 and 15.
 235
 236 .TP
 237 .BI --msisdn " msisdn"
 238 .I msisdn
 239 to use when connecting to the GGSN (default = 46702123456). MSISDN is
 240 an abbreviation of International Mobile Integrated Services Digital
 241 Network. Effectly a phone number in international format without the
 242 leading 00 or 011. See the
 243 .I contexts
 244 option for the the use of the
 245 .I msisdn
 246 option with multiple contexts.
 247
 248 .TP
 249 .BI --qos " qos"
 250 .I qos
 251 to use when connecting to the GGSN (default = 0x0b921f). QoS is an
 252 abbreviation of Quality of Service. See 3GPP specification 09.60 for
 253 the format of this string.
 254
 255 .TP
 256 .BI --charging " charging"
 257 Charging characteristics to use when connecting to the GGSN (default =
 258 0x0800). 0x0800 = Normal, 0x0400 = Prepaid, 0x0200 = Flat rate, 0x0100
 259 = Hot billing. See 3GPP specification 32.015 for the format of this
 260 field.
 261
 262 .TP
 263 .BI --uid " uid"
 264 User ID to send to GGSN as protocol configuration option.
 265
 266 .TP
 267 .BI --pwd " pws"
 268 Password to send to GGSN as protocol configuration option.
 269
 270 .TP
 271 .BI --createif
 272 Create a local tun interface. This interface will be used for
 273 forwarding packets to and from the Gn/Gp interface. Use with caution
 274 as the Gn/Gp interface is normally be routed to the Internet by the
 275 GGSN. Only one interface will be created, even if several contexts are
 276 established. The interface will be given an IP address for each
 277 established context, or the address can be specified with the
 278 .I net
 279 option.
 280
 281 .TP
 282 .BI --net " net"
 283 Network address of the local interface. The
 284 .I net
 285 option is only valid when the
 286 .I createif
 287 option is used. The
 288 .I net
 289 option is given in cidr format (net/mask bits). If the
 290 .I net
 291 option omitted an IP address is allocated for each context established.
 292
 293 .TP
 294 .BI --defaultroute
 295 Create a defaultroute to the local tun interface.
 296
 297 .TP
 298 .BI --ipup " script"
 299 Script executed after the tun network interface has been brought up.
 300 Executed with the following parameters: <devicename> <ip address>
 301
 302 .TP
 303 .BI --ipdown " script"
 304 Script executed after the tun network interface has been taken down.
 305 Executed with the following parameters: <devicename> <ip address>
 306
 307 .TP
 308 .BI --pinghost " host"
 309 Ping
 310 .I host
 311 through the Gn/GP interface. Ping statistics are reported much like
 312 done by the original ping program. Use this facility for performance
 313 test of GGSNs.
 314
 315 .TP
 316 .BI --pingrate " num"
 317 Number of ping requests per second (default = 1)
 318
 319 .TP
 320 .BI --pingsize " num"
 321 The size of each ping requests in octets (default = 56)
 322
 323
 324 .TP
 325 .BI --pingcount " num"
 326 Number of ping requests to send (default = 0). A value of 0 (zero)
 327 indicates infinite.
 328
 329 .TP
 330 .BI --pingquiet
 331 Do not print information for each packet received (default = off). Is
 332 quite usefull for high pingrates.
 333
 334
 335 .SH FILES
 336 .I sgsnemu.conf
 337 .RS
 338 The configuration file for
 339 .B sgsnemu.
 340 .RE
 341 .I .sgsnemu.pid
 342 .RS
 343 Process ID file.
 344 .RE
 345 .I ./
 346 .RS
 347 Directory holding nonvolatile data.
 348 .RE
 349
 350 .SH BUGS
 351 Report all bugs to the OpenGGSN bug tracking list at
 352 .I http://sourceforge.net/projects/sgsnemu/
 353
 354
 355 .SH "SEE ALSO"
 356 .BR ggsn (8)
 357
 358 .SH NOTES
 359 .LP
 360
 361 Besides the long options documented in this man page
 362 .B sgsnemu
 363 also accepts a number of short options with the same functionality. Use
 364 .B sgsnemu --help
 365 for a full list of all the available options.
 366
 367 The TUN/TAP driver is required for proper operation of
 368 .B sgsnemu.
 369 For linux kernels later than 2.4.7 the TUN/TAP driver is included in
 370 the kernel, but typically needs to be loaded manually with
 371 .B modprobe tun.
 372 For automatic loading the line
 373 .B alias char-major-10-200 tun
 374 can be added to
 375 .B /etc/modules.conf.
 376 For other platforms see
 377 .I http://vtun.sourceforge.net/tun/
 378 for information on how to install and configure the tun driver.
 379
 380 .B sgsnemu
 381 uses the GPRS Tunneling Protocol (GTP) as specified by the Third
 382 Generation Partnership Project (3GPP). 3GPP protocols specifications
 383 can be found at
 384 .I http://www.3gpp.org
 385
 386 .SH COPYRIGHT
 387
 388 Copyright (C) 2002, 2003, 2004 by Mondru AB.
 389
 390 The contents of this file may be used under the terms of the GNU
 391 General Public License Version 2, provided that the above copyright
 392 notice and this permission notice is included in all copies or
 393 substantial portions of the software.
 394
 395 .SH AUTHORS
 396 Jens Jakobsen <jj@openggsn.org>