doc/sgsnemu.8

.\" * OsmoGGSN - Gateway GPRS Support Node
.\" * Copyright (C) 2002, 2003 Mondru AB.
.\" * 
.\" * The contents of this file may be used under the terms of the GNU
.\" * General Public License Version 2, provided that the above copyright
.\" * notice and this permission notice is included in all copies or
.\" * substantial portions of the software.
.\" * 
.\" * The initial developer of the original code is
.\" * Jens Jakobsen <jj@openggsn.org>
.\" * 
.\" * Contributor(s):
.\" * 
.\" Manual page for ggsn
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
.\" IP indented paragraph
.\" TP hanging label

.TH sgsnemu 8 "May 2004"
.SH NAME
sgsnemu \- Serving GPRS Support Node Emulator
.SH SYNOPSIS
.B sgsnemu
\-\-help

.B sgsnemu
\-\-version

.B sgsnemu
[
.BI \-\-debug
] [
.BI \-\-conf " file"
] [
.BI \-\-pidfile " file"
] [
.BI \-\-statedir " file" 
] [ 
.BI \-\-dns " host"
] [ 
.BI \-\-listen " host" 
] [
.BI \-\-remote " host"
] [
.BI \-\-contexts " num"
] [
.BI \-\-timelimit " seconds" 
] [
.BI \-\-gtpversion " version"
] [
.BI \-\-apn " apn"
] [
.BI \-\-selmode " selmode"
] [
.BI \-\-imsi " imsi"
] [
.BI \-\-nsapi " nsapi"
] [
.BI \-\-msisdn " msisdn"
] [
.BI \-\-qos " qos"
] [
.BI \-\-charging " charging"
] [
.BI \-\-uid " uid"
] [
.BI \-\-pwd " pwd"
] [
.BI \-\-createif
] [
.BI \-\-net " net" 
] [
.BI \-\-defaultroute
] [
.BI \-\-ipup " script" 
] [
.BI \-\-ipdown " script" 
] [
.BI \-\-pinghost " host"
] [
.BI \-\-pingrate " num"
] [
.BI \-\-pingsize " num"
] [
.BI \-\-pingcount " num"
]
.SH DESCRIPTION
.B sgsnemu
is part of the 
.B OsmoGGSN
project, and implements a Serving GPRS Support Node (SGSN)
emulator. It can be used for testing Gateway GPRS Support Nodes
(GGSNs), GPRS core networks as well as GPRS roaming connections.

The GPRS functionality and protocols has been standardised by the
Third Generation Partnership Project (3GPP). According to the 3GPP
specifications an SGSN has several interfaces.
.B sgsnemu
implements the Gn/Gp interface which is used towards GGSNs.

The Gn/Gp interface can be seen as the uplink interface of the
SGSN. It is used for communicating with a GGSN which is typically
connected to the Internet. The Gn/Gp interface uses the GPRS tunneling
protocol (GTP). User data packets (typically IP packets) are tunneled
over GTP, which again uses UDP over IP.


.B sgsnemu 
will establish a number of connections to the GGSN. An internal ping
facility will transmit ping requests through the established
connections. Alternatively a local network interface can be
created. In this case
.B sgsnemu
will forward packets between the local network interface and the
established connections on the Gn/Gp interface.

.B sgsnemu
uses the 
.B TUN/TAP driver
for the local interface. A tun network interface is established for
each connection established to the GGSN.

Runtime errors are reported using the Osmocom logging framework.


.SH OPTIONS
.TP
.BI --help
Print help and exit.

.TP
.BI --version
Print version and exit.

.TP
.BI --debug
Run in debug mode (default = off)

.TP
.BI --conf " file"
Read configuration 
.I file
where each line corresponds to one command line option, but with the
leading '--' removed. Command line options override the options given
in the configuration file.

.TP
.BI --pidfile " file"
Filename of process id 
.I file
(default = ./sgsnemu.pid)

.TP
.BI --statedir " path"
.I path
to directory of nonvolatile data (default = ./)

.TP
.BI --dns " host"
DNS server to use for APN lookups. If omitted the default system DNS
configuration will be used.

.TP
.BI --listen " host"
Local interface IP address to use for the Gn/Gp interface. If omitted
.B sgsnemu
will listen to any IP address.

.TP
.BI --remote " host"
GGSN 
.I host
to connect to. If DNS is setup correctly it should be possible to
specify the access point name (APN) as the remote host.

.TP
.BI --contexts " num"
Number of contexts to establish. (default = 1). For multiple contexts
the the first context is established using imsi + 0 and msisdn +
0. The second context is established using imsi + 1 and msisdn +
1. The third....

.TP
.BI --timelimit " seconds"
Exit 
.B sgsnemu
after 
.I seconds. 
When using the ping facility 
.B sgsnemu
will also exit after
.B --pingcount
packets has been transmitted.

.TP
.BI --gtpversion " version"
.I version
of GTP to use when establishing a context (default = 1). If not able
to establish a GTPv1 context sgsnemu will fall back to using GTPv0.

.TP
.BI --apn " apn"
.I apn
to use when connecting to the GGSN (default = internet). APN is an
abbreviation of Access Point Name.

.TP
.BI --selmode " selmode"
Selection mode to use when connecting to the GGSN (default =
0x01). The encoding of the selection mode is as follows: 0: MS or
network provided APN, subscribed verified, 1: MS provided APN,
subscription not verified, 2: Network provided APN, subscription not
verified.


.TP
.BI --imsi " imsi"
.I imsi
to use when connecting to the GGSN (default = 240010123456789). IMSI
is an abbreviation of International Mobile Subscriber Identity. Must
be exactly 15 digits. See the
.I contexts
option for the the use of the
.I imsi
option with multiple contexts.

.TP
.BI --nsapi " nsapi"
.I nsapi
to use when connecting to the GGSN (default = 0). Must be between 0
and 15.

.TP
.BI --msisdn " msisdn"
.I msisdn
to use when connecting to the GGSN (default = 46702123456). MSISDN is
an abbreviation of International Mobile Integrated Services Digital
Network. Effectly a phone number in international format without the
leading 00 or 011. See the
.I contexts
option for the the use of the
.I msisdn
option with multiple contexts.

.TP
.BI --qos " qos"
.I qos
to use when connecting to the GGSN (default = 0x0b921f). QoS is an
abbreviation of Quality of Service. See 3GPP specification 09.60 for
the format of this string.

.TP
.BI --charging " charging"
Charging characteristics to use when connecting to the GGSN (default =
0x0800). 0x0800 = Normal, 0x0400 = Prepaid, 0x0200 = Flat rate, 0x0100
= Hot billing. See 3GPP specification 32.015 for the format of this
field.

.TP
.BI --uid " uid"
User ID to send to GGSN as protocol configuration option.

.TP
.BI --pwd " pws"
Password to send to GGSN as protocol configuration option.

.TP
.BI --createif
Create a local tun interface. This interface will be used for
forwarding packets to and from the Gn/Gp interface. Use with caution
as the Gn/Gp interface is normally be routed to the Internet by the
GGSN. Only one interface will be created, even if several contexts are
established. The interface will be given an IP address for each
established context, or the address can be specified with the
.I net
option.

.TP
.BI --net " net"
Network address of the local interface. The 
.I net
option is only valid when the
.I createif
option is used. The
.I net
option is given in cidr format (net/mask bits). If the
.I net
option omitted an IP address is allocated for each context established.

.TP
.BI --defaultroute
Create a defaultroute to the local tun interface.

.TP
.BI --ipup " script"
Script executed after the tun network interface has been brought up.
Executed with the following parameters: <devicename> <ip address>

.TP
.BI --ipdown " script"
Script executed after the tun network interface has been taken down.
Executed with the following parameters: <devicename> <ip address>

.TP
.BI --pinghost " host"
Ping
.I host
through the Gn/GP interface. Ping statistics are reported much like
done by the original ping program. Use this facility for performance
test of GGSNs.

.TP
.BI --pingrate " num"
Number of ping requests per second (default = 1)

.TP
.BI --pingsize " num"
The size of each ping requests in octets (default = 56)


.TP
.BI --pingcount " num"
Number of ping requests to send (default = 0). A value of 0 (zero)
indicates infinite.

.TP
.BI --pingquiet
Do not print information for each packet received (default = off). Is
quite useful for high pingrates.


.SH FILES
.I sgsnemu.conf
.RS
The configuration file for
.B sgsnemu.
.RE
.I .sgsnemu.pid
.RS
Process ID file.
.RE
.I ./
.RS
Directory holding nonvolatile data.
.RE

.SH BUGS
Report all bugs to the OsmoGGSN bug tracking list at 
.I http://osmocom.org/projects/openggsn/issues


.SH "SEE ALSO"
.BR ggsn (8)

.SH NOTES 
.LP

Besides the long options documented in this man page
.B sgsnemu
also accepts a number of short options with the same functionality. Use
.B sgsnemu --help
for a full list of all the available options.

The TUN/TAP driver is required for proper operation of
.B sgsnemu. 
For linux kernels later than 2.4.7 the TUN/TAP driver is included in
the kernel, but typically needs to be loaded manually with
.B modprobe tun.
For automatic loading the line
.B alias char-major-10-200 tun
can be added to
.B /etc/modules.conf.
For other platforms see
.I http://vtun.sourceforge.net/tun/
for information on how to install and configure the tun driver.

.B sgsnemu 
uses the GPRS Tunneling Protocol (GTP) as specified by the Third
Generation Partnership Project (3GPP). 3GPP protocols specifications
can be found at
.I http://www.3gpp.org

.SH COPYRIGHT

Copyright (C) 2002, 2003, 2004 by Mondru AB.

The contents of this file may be used under the terms of the GNU
General Public License Version 2, provided that the above copyright
notice and this permission notice is included in all copies or
substantial portions of the software.

.SH AUTHORS
Jens Jakobsen <jj@openggsn.org>