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