Posted by eltjoboersma
on April 22, 2008 at 8:03 AM PDT
SailFin adds SIP to the JEE equation, SIP takes a slight different, more elaborate, approach on address and ports than HTTP does. Here I will provide an overview how the configuration model for SailFin looks like and how you can configure it to your needs.
SailFin adds SIP to the JEE equation, SIP takes a slight different, more elaborate, approach on address and ports than HTTP does.
Approach and concepts
Still for SailFin we tried to align as much as possible to the configuration model of the web container.
I.e. we introduced sip-service
much in line with the http-service
(however we do not use the concept of virual servers) and have sip-listeners
within this sip-service similar to the http-listeners
Note that these concepts are how you'll find them when using the asadmin console commands and in the domain.xml. In the GUI they are indicated with some more friendly names.
There is also the concept of a sip-container
that is derived from the web-container
and other containers.
I won't go into every tiny detail of these concepts, but will focus on the address and port settings. Also I will not talk about the converged loadbalancer settings and I won't go much into details on cluster settings either, that is perhaps stuff for a future blog. For configuring addresses and ports we have to take a closer look at the sip-listener and sip-container.
The server port on which the sip container listens on for things like incoming INVITES can be configured using a sip-listener. There can be multiple configured. SailFin comes with the default port as defined in the SIP specification 5060. Lets have a look at these settings: Type the following on the console of a running SailFin with default domain.
asadmin> list server.sip-service.sip-listener.*
This should result in the following list:
There are two sip-listeners; sip-listener-1 and sip-listener-2 (which has a ssl part attached it). They relate to what in SIP terms are called the SIP and a SIPS port. Letâ€™s have a closer look at the sip-listener-1, the SIP port. Typing the following reveals the details:
asadmin> get server.sip-service.sip-listener.sip-listener-1.*
server.sip-service.sip-listener.sip-listener-1.address = 0.0.0.0
server.sip-service.sip-listener.sip-listener-1.enabled = true
server.sip-service.sip-listener.sip-listener-1.id = sip-listener-1
server.sip-service.sip-listener.sip-listener-1.port = 5060
server.sip-service.sip-listener.sip-listener-1.transport = udp_tcp
What we see is to some extend what we expected. A port set to 5060 and an address set to 0.0.0.0. The 0.0.0.0 address is what we call a BIND to ANY address and which allows you to bind the server socket to any of your network interfaces on your system.
There is also this attribute transport that you won't find when configuring the web container. SIP requires that the sip container (the user agent server or UAS in SIP terms) opens the same port not only for the TCP protocol but also for the UDP protocol. They are tied together, you could say. This allows SIP clients and servers during session establishment to choose the transport protocol to use. This is indicated with the udp_tcp value of the transport.
The remaining attributes are id and enabled which do exactly what the name suggests.
I guess you are wondering why this sip-listener-2, we already covered TCP and UDP connectivity with sip-listener-1? Letâ€™s have a look at it, type the following:
asadmin> get server.sip-service.sip-listener.sip-listener-2.*
server.sip-service.sip-listener.sip-listener-2.address = 0.0.0.0
server.sip-service.sip-listener.sip-listener-2.enabled = true
server.sip-service.sip-listener.sip-listener-2.id = sip-listener-2
server.sip-service.sip-listener.sip-listener-2.port = 5061
server.sip-service.sip-listener.sip-listener-2.transport = tls
Next to a different port 5061, which is again a predefined default from the SIP spec, we see a transport protocol tls. TLS as you might know supersedes SSL, so it is the secure counter part of the TCP protocol. Indeed the sip-listener-2 represents the SIPS port much inline with the HTTPS port for the web container. Just like the http-listener a ssl part can be attached to configure the security settings for TLS sessions. I will not go into those details here.
So why 5061 and not just 5060? The reason is that TLS is based on TCP and it would cause a port conflict.
Now we know a bit about the sip-listener concept. Letâ€™s have look at some typical task you might want to perform. First thing we see often on the dev-list of SailFin is changing the default setting, such as the port. Here is how you do it.
asadmin> set server.sip-service.sip-listener.sip-listener-1.port=5065
server.sip-service.sip-listener.sip-listener-1.port = 5065
The new port is 5065, letâ€™s see if it really worked. First check whether the setting was registered on the console:
asadmin> get server.sip-service.sip-listener.sip-listener-1.port
server.sip-service.sip-listener.sip-listener-1.port = 5065
I hope you are seeing a pattern emerging with these asadmin command, there is some simple logic behind it. Like get and set, etc. You should be able to change to other attributes as well I recon.
Nice, but is the SIP container really listening on 5065... Simplest way to check if it does is to check with something like netstat. On windows it would be as such:
Proto Local Address Foreign Address State
TCP xxxxxxx:4848 xxxxxxx.ericsson.se:0 LISTENING
TCP xxxxxxx:5061 xxxxxxx.ericsson.se:0 LISTENING
TCP xxxxxxx:5065 xxxxxxx.ericsson.se:0 LISTENING
TCP xxxxxxx:8080 xxxxxxx.ericsson.se:0 LISTENING
TCP xxxxxxx:8181 xxxxxxx.ericsson.se:0 LISTENING
UDP xxxxxxx:5065 *:*
As you can see the 5065 is there for both UDP and TCP and there is no trace of the 5060 port. Still there is the 5061 port, which makes sense as it is correlated to sip-listener-2. The other ports are the ports opened by glassfish for admin and the web container.
For real proof you have to run some test client against the SIP container of course, but I will leave that for you to try out.
One warning is appropriate though, we just showed you that SailFin allows you to change a sip-listener during runtime, which is extremely flexible, but currently it won't consider the consequences of the change, so if there was any communication ongoing on 5060 we would have disrupted it. Even disabling the sip-listener is disruptive at the moment. You will need to plan ahead with changing the sip-listeners and do it in the quiet hours. Note that when you have bigger configuration with a cluster, ipsprayer and load balancer in place there are techniques at your disposal to have more control. This is an evolving area and I am sure steps will be made.
What about adding new sip-listeners or deleting them? That's also possible, for this there are special asadmin commands. Here is how to add a sip-listener called 'blabla' that binds to localhost on port 5066.
asadmin> create-sip-listener --siplisteneraddress=127.0.0.1 --siplistenerport=5066 --transport=udp_tcp blabla
Command create-sip-listener executed successfully.
You can check whether it worked in the same way as explained above. Notice the --siplisteneraddress and --siplistenerport like all asadmin commands it already has a --address and --port argument which you use when managing a remote GlassFish / SailFin therefore it was necessary to add the siplistener prefix to distinguish the address and port.
To complete our sip-listener life cycle here is how to remove it again:
asadmin> delete-sip-listener blabla
Command delete-sip-listener executed successfully.
By now you might wonder, what's more to it than configuring server ports? We are not done yet, though. In SIP communication is two-way and multiple interactions are needed to establish and teardown a session. Also a SipServlet or Converged application can initiate a session of its own (as a result of some other application event) to an external server (UAS) or client (UAC) without prior communication with this server or client. To allow the external party to call back it needs to know the address and port to reach. SIP has foreseen in this and allows the SIP Container to provide CONTACT and VIA headers in the SIP messages, fortunately as an SipServlet application you don't need to worry much about these details.
But hold on, these 'callbacks', wouldn't these arrive eventually on the sip-listener port... They would! But, and here it comes, the sip-listener ports are not necessary visible outside the system running the application. This is obvious when we consider a full blown cluster where there are multiple server instances running all with their own addresses etc. there won't be much loadbalancing if we give out these addresses away i.e. and they most likely are not accessible externally. Also in a smaller setup you can encounter similar visibility issues, think of your NAT and external ip address, they most likely are different than your setting of the sip-listener.
To solve this, the sip-container concept is equipped with some attributes that allows you to configure the externally visible address and port.
Lets have a look:
asadmin> get server.sip-container.*
server.sip-container.external-sip-port = 5060
server.sip-container.external-sips-port = 5061
And indeed there is an external-address and two ports, one for SIP (external-sip-port) and the other for SIPS (external-sips-port), so no transport here. These are the default.
The external-address is empty! This doesn't mean that an empty CONTACT header is signaled to our external parties. The SIP Container has a heuristic that tries to find a suitable address by examining all network interfaces on the machine. Unfortunately the heuristic needs some brushing up (see issue 457), but note that this feature is only for your convenience, the container attempts to have a default setting that runs out of the box; you can always provide the proper external-address manually. In a cluster setup it is mandatory to change the external-address. In most cases to the address of the ip-sprayer.
If you are really observant, you noticed that the change we did to the port of sip-listener-1 has not affected the external-sip-port. Although the default behavior might be change to follow the sip-listeners in the future (there are several interesting things to consider here, feel free to post any suggestion on how you would like to see it working), for now you have to do that manually. Here is how it can be done:
asadmin> set server.sip-container.external-sip-port=5065
server.sip-container.external-sip-port = 5065
That's it for now, hope this helps you configure SailFin to your liking.