README.rst
1.. image:: https://travis-ci.org/jtriley/pystun.svg?branch=master
2 :target: https://travis-ci.org/jtriley/pystun
3
4.. image:: https://coveralls.io/repos/jtriley/pystun/badge.png
5 :target: https://coveralls.io/r/jtriley/pystun
6
7
8PyStun
9======
10A Python STUN client for getting NAT type and external IP
11
12This is a fork of pystun originally created by gaohawk (http://code.google.com/p/pystun/)
13
14PyStun follows RFC 3489: http://www.ietf.org/rfc/rfc3489.txt
15
16A server following STUN-bis hasn't been found on internet so RFC3489 is the
17only implementation.
18
19Installation
20------------
21To install the latest version::
22
23 $ pip install pystun
24
25or download/clone the source and install manually using::
26
27 $ cd /path/to/pystun/src
28 $ python setup.py install
29
30If you're hacking on pystun you should use the 'develop' command instead::
31
32 $ python setup.py develop
33
34This will make a link to the sources inside your site-packages directory so
35that any changes are immediately available for testing.
36
37Usage
38-----
39From command line::
40
41 $ pystun
42 NAT Type: Full Cone
43 External IP: <your-ip-here>
44 External Port: 54320
45
46Pass --help for more options::
47
48 % pystun --help
49 usage: pystun [-h] [-d] [-H STUN_HOST] [-P STUN_PORT] [-i SOURCE_IP]
50 [-p SOURCE_PORT] [--version]
51
52 optional arguments:
53 -h, --help show this help message and exit
54 -d, --debug Enable debug logging (default: False)
55 -H STUN_HOST, --host STUN_HOST
56 STUN host to use (default: None)
57 -P STUN_PORT, --host-port STUN_PORT
58 STUN host port to use (default: 3478)
59 -i SOURCE_IP, --interface SOURCE_IP
60 network interface for client (default: 0.0.0.0)
61 -p SOURCE_PORT, --port SOURCE_PORT
62 port to listen on for client (default: 54320)
63 --version show program's version number and exit
64
65From Python::
66
67 import stun
68 nat_type, external_ip, external_port = stun.get_ip_info()
69
70This will rotate through an internal list of STUN servers until a response is
71found. If no response is found you will get "Blocked" as the *nat_type* and
72**None** for *external_ip* and *external_port*.
73
74If you prefer to use a specific STUN server::
75
76 nat_type, external_ip, external_port = stun.get_ip_info(stun_host='stun.ekiga.net')
77
78If you prefer to use a specific STUN server port::
79
80 nat_type, external_ip, external_port = stun.get_ip_info(stun_port=3478)
81
82You may also specify the client interface and port that is used although this
83is not needed::
84
85 sip = "0.0.0.0" # interface to listen on (all)
86 port = 54320 # port to listen on
87 nat_type, external_ip, external_port = stun.get_ip_info(sip, port)
88
89Read the code for more details...
90
91LICENSE
92-------
93MIT
94
