TUTORIAL: Quickstart with freeDiameter - Quickstart a... · How to compile and run freeDiameter in...
Transcript of TUTORIAL: Quickstart with freeDiameter - Quickstart a... · How to compile and run freeDiameter in...
How to compile and run freeDiameter in a simple testbed.
TUTORIAL: Quickstart with freeDiameter
2010/3/15
38
Souheil Ben Ayed, Sebastien Decugis
Tutorial: Creating a fD testbed
2010/3/15
39
Goal : create a simple testbed
Two nodes: one client, one server
Run a test application “ping”-like
What you need:
Two machines (with FQDN in same realm for simplicity)
An X.509 certificate hierarchy (CA, 2 certs)
See contrib/ca_script for a script for openssl.
Souheil Ben Ayed, Sebastien Decugis
Prerequisites (in INSTALL file)
2010/3/15
40
freeDiameter dependencies (debian packages)
Tools: mercurial, cmake, flex, bison, gcc, make
Libs: libsctp-dev, libgcrypt-dev, libgnutls-dev
Install all these with your package manager (ex: apt-get)
Get the latest freeDiameter version:
1st time: hg clone http://aaa.koganei.wide.ad.jp/hg/freeDiameter/
Later: hg pull ; hg update
Good Mercurial tutorial: http://hginit.com
Souheil Ben Ayed, Sebastien Decugis
Preparing freeDiameter: cmake
2010/3/15
41
cmake is an autotools equivalent with simpler syntax
cmake or cmake-gui
Choose the options:
Extensions,
Dependencies paths,
Debug, etc…
Generate:
create the Makefile
(same as ./configure)
Souheil Ben Ayed, Sebastien Decugis
cmake in our tutorial
2010/3/15
42
Prepare a build directory (out of source):
mkdir build && cd build
We use these flags (cmake-gui is more friendly):
-DBUILD_TEST_APP:BOOL=ON : Include the test application extension
-DBUILD_DBG_MONITOR:BOOL=ON : Display some information
-DSKIP_TESTS:BOOL=ON : Do not compile the unit tests
-DCMAKE_BUILD_TYPE:STRING=Debug : include debug symbols for gdb
Generate & check system dependencies:
cmake $FLAGS /path/to/source
Souheil Ben Ayed, Sebastien Decugis
cmake output
2010/3/15
43
After running the command you should see:
-- Configuring done
-- Generating done
-- Build files have been written to: …/build
You can check the generated files, in particular:
CMakeCache.txt : contains all configured options
include/freeDiameter/freeDiameter-host.h :
machine-dependent values (such as endianness …)
Souheil Ben Ayed, Sebastien Decugis
Compiling freeDiameter: make
2010/3/15
44
Just issue make in the build directory.
If you want more information: make VERBOSE=1
Some usual targets are supported, such as make clean
Souheil Ben Ayed, Sebastien Decugis
freeDiameter configuration file
2010/3/15
45
Create 2 files fD.conf as follow:
LoadExtension = "extensions/test_app.fdx";
LoadExtension = "extensions/dbg_monitor.fdx";
TLS_Cred = ".../cert.pem", ".../privkey.pem";
ConnectPeer = "serv.testbed";
Adapt the paths and peer names to each peer.
`hostname –fqdn` must work properly with this simple file.
Otherwise, add: Identity = "my.diam.id";
You can configure the test application (see sample conf)
Souheil Ben Ayed, Sebastien Decugis
Understanding test_app
2010/3/15
46
Test-app is a « ping » application (not standard)
Showcase of many features, using all basic functions.
More details in part III of the tutorial
Souheil Ben Ayed, Sebastien Decugis
Running the daemon
2010/3/15
47
./freeDiameter/freeDiameterd –h
-c : configuration file
-d ,-q : increase, decrease verbosity
./freeDiameter/freeDiameterd –dd –c fD.conf
…
All extensions loaded.
-- Configuration :
…
freeDiameter daemon initialized.
Terminate with ^C (`kill –TERM $PID`)
Souheil Ben Ayed, Sebastien Decugis
Running the test
2010/3/15
48
Start the daemon on both peers.
Check the connection is established
the dbg_monitor extensions shows status every 30 secs
the other peer must appear in STATE_OPEN state.
Send SIGUSR1 to the client’s daemon (kill –USR1 $PID)
This is the test_app trigger to send the “ping” request.
Check these lines appear on the console:
SEND 74b0dc51 to ‘serv.testbed.net' (testbed.net)
RECV 74b0dc51 (Ok) Status: 2001 From'serv.testbed.net' ('testbed.net') in 0.062237 sec
Souheil Ben Ayed, Sebastien Decugis
Murphy’s law: If anything can go wrong, it will
Live demonstration – running test_app
2010/3/15
49
Souheil Ben Ayed, Sebastien Decugis
Debugging freeDiameter
2010/3/15
50
And if it does not work? How to debug?
Multi-threaded: a debugger is difficult to use
But still useful in case of “core dump”
Useful gdb command: threads apply all where
Breakpoints are sometimes helpful
Easy to set when using macro TRACE_HERE()
Good news: tracing is very easy with freeDiameter!
Use CHECK_* , TRACE_* macro (even in extensions)
Exemple: CHECK_FCT_DO(_call_, _fallback_)
Trace (level CALL:9), execute _call_.
If it returns an error, trace (level INFO:1), execute _fallback_
Souheil Ben Ayed, Sebastien Decugis
Traces format explained
2010/3/15
51
tid:PSM/proxy.b.rt… Identifies the thread, here the PSM of proxy.b.rt… peer
02/23/10,17:18:07.175282 The timestamp of this trace.
in [email protected]:984 Function, file, line where the trace was issued.
@| Unknown address family returned in … @ : Marks an important line (level >= INFO, usually errors)
The message itself.
Souheil Ben Ayed, Sebastien Decugis
Tracing freeDiameter
2010/3/15
52
To obtain more traces :
First option : use more -d flag.
Ex: freeDiameterd –ddd –c fD.conf
Max level (10): almost all calls are displayed.
Unusable in most cases: changes the dynamics, fills the HDD
Recommended: -dd when debugging, none or –q otherwise.
Second option: localized verbosity.
--dbg_func=<func>
The debug level is maximum only inside this function
--dbg_file=<file>
The debug level is maximum only for this file.
To save the output: … | tee –i logfile.txt
Souheil Ben Ayed, Sebastien Decugis
Murphy’s law:
Given the most inappropriate time for something to go wrong, that's when it will occur.
Live demonstration – log file content
2010/3/15
53
Souheil Ben Ayed, Sebastien Decugis
End of part II.
Thank you for listening!
Any question at this
point?
Next: Part III -
Writing an extension
2010/3/15
54
Souheil Ben Ayed, Sebastien Decugis