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.


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


http://hginit.com/

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)


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


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 …)


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


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)


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


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`)


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


Murphy’s law: If anything can go wrong, it will

Live demonstration – running test_app

2010/3/15

49


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_


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.


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


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


End of part II.

Thank you for listening!

Any question at this

point?

Next: Part III -

Writing an extension

2010/3/15

54


TUTORIAL: Quickstart with freeDiameter - Quickstart a... · How to compile and run freeDiameter in...

Documents

Transcript of TUTORIAL: Quickstart with freeDiameter - Quickstart a... · How to compile and run freeDiameter in...