[OpenSER-Users] OpenSER Docs?

[Klaus Darilion]

Douglas Garstang wrote:
> So.. I've been using OpenSER for about 2 years now and it's still mostly 
> a mystery to me. Just about everything I have done with it has been my 
> observation and reverse engineering.
> 
> Apart from the API specs on openser.org <http://openser.org/>, which are 
> NOT documentation, does any good documentation exist?

IMO the README of the modules are a good documentation.

> Are there any books on SER/OpenSER?

I think there is a german one which covers ser, which might be in some 
aspects interesting for openser users too.
> 
> Where can I find good documentation with examples on the use of avpops? 

- the avpops README http://www.openser.org/docs/modules/1.3.x/avpops.html
- probably outdated, but still gives some ideas about the aVP concept:
http://www.voice-sistem.ro/docs/avpops/

> Why append_branch is required, and other mysteries?

Ok. append_branch is really a mystery.

I really suggest you to read all the slides from admin course from VON fall:
http://www.openser.org/mos/view/OpenSER-Admin-Course---Boston-2007/

It will take you 1 day to read them all, but for sure it will help you a 
lot.

regards
klaus

PS: append_branch (guys, please correct me if I am wrong)
When you do forking in a SIP proxy (parallel or sequential), the 
different calls are called "branches". Internally, openser keeps all 
destination as branches, which are linked to the respective msg 
structure. The msg structure has the branch[0] (more or less the main 
branch, the request URI), and all the other branches.

For example you want to forking an incoming call to B & C & D:

# incoming request
$ru = "sip:b at b.com";
# now, the ruri is set to B
#
# now we will add another branch to call C too
append_branch("sip:c at c.com");
# now, the append_branch function has created a new branch
# inside the current msg structure and set it to C
#
# now lets add D as destination too, this time we use
# another approach
append_branch();
# now, the append_branch function has created a new branch
# and the destination inside the new branch is copied from the
# request URI. Thus, now we have 3 destinations:
# RURI (branch[0]): B
# branch[1]: C
# branch[2]: B
$ru = "sip:d at d.com";
# now we have 3 destinations:
# RURI (branch[0]): D
# branch[1]: C
# branch[2]: B
#
# now we activate a failure route to demonstrate append_branch in
# failure route too:
t_on_failure("1");
# forward the request in parallel to all 3 destination
t_relay();
exit



failure_route[1] {
	# as we enter the failure route this means that
	# all 3 branches have failed (timeout or error response).
	#
	# we will now as example add another 2 destination X&Y to
	# and forward it in parallel again:
	#
	# current state of the msg structure:
	#  RURI (branch[0]): D
	#  branch[1]: C
	#  branch[2]: B
	# thus, these branches are still present, but internally
	# marked as "failed", thus when calling t_relay() again
	# these "failed" branches wont be used. Thus,
	# $ru = "sip:x at x"; t_relay(); wont work. It will set
	# the RURI (branch[0]) to the new destination, but as
	# branch[0} is still marked as "failed" it wont be used.
	# Thus in failure route it is mandatory to use append_branch()
	# except it is set internally by some functions
	# (e.g. dispatcher).
	$ru = "sip:x at x.com";	# branch[0] = X (still marked as failed)
	append_branch();	# branch[3] = X;
	append_branch("sip:y at y.com"); # branch[4] = Y;
	t_relay();
	exit;
}