A JAIN-SIP Proxy For the People!
A JAIN-SIP Proxy for the People!
1. What's in this package?
This package contains the source code of a JAVA based SIP proxy built
on top of the
JAIN-SIP-1.1 API.
The source code for this package is located in examples/proxy. The proxy
is a pure JAIN-SIP application: it does not need proprietary nist-sip
classes in addition of those defined in JAIN-SIP 1.1, you can substitute
the NIST-SIP stack by another JAIN-SIP-1.1 compliant stack and it should
interoperate.
The proxy also functions as a SIP registrar and a SIP presence server.
2. Proxy capabilities
- Presence Server capability:
The proxy can act as presence server and be able to process NOTIFY and
SUBSCRIBE requests. If this parameter is disabled, the proxy will simply
forward those kind of requests following the appropriate routing decision.
- ROUTE and RECORD-ROUTE headers process:
The proxy is
able to add and process the RECORD-ROUTE and ROUTE headers specified
in the request. Therefore, it is possible to use multiple proxies to
establish the sessions.
- Registrations uploading:
You can specify a set of registrations that will be uploaded into the proxy
at start-up time. The file to modify is "registrations.xml" located in the
"examples/proxy/configuration/" directory.
- Server authentication:
The proxy can authenticate all the requests that it receives. The default authentication method
is DIGEST and it is the only one supported for now.
- Forking capability:
The proxy can fork the INVITE requests it receives.
3. The XML configuration file
The proxy has to be initialized via a configuration XML file. Here are a description of each of
the parameters that you can set up.
- SIP_STACK tag:
This tag is mandatory, it defines the core parameters of the stack.
- stack_name parameter:
Use it to define the name associated with the
stack. This is just an arbitrary string identifier. MANDATORY.
- stack_IP_address parameter:
Defines the IP address used to start the stack. MANDATORY.
- outbound_proxy parameter:
Defines the next hop used by the proxy
to forward the messages in case when no informations worked to route the messages!!
Do not put the proxy address in!!! Otherwise, the messages will be send to the proxy itself
and it will loop!!! OPTIONAL.
- router_path parameter:
The java class name of the router used by the stack to resolve the location to forward
the messages to. OPTIONAL.
- extension_methods parameter:
OPTIONAL.
- retransmission_filter parameter:
OPTIONAL.
- stop_after parameter:
Defines the time in seconds after when the proxy will stop. OPTIONAL.
- stack_domain parameter:
Defines the domain that the proxy has to take care of. example: nist.gov
It has to be used with the registrations.xml file to be relevant.
OPTIONAL.
- LISTENING_POINT tag:
At least one tag has to be specified. Defines the listening points for the stack
for incoming and outgoing messages. MANDATORY.
- port parameter:
Use it to define the port of this specific listening point. MANDATORY.
- transport parameter:
Use it to define the transport (UDP or TCP) of this specific listening point. MANDATORY.
- REGISTRAR tag:
This tag exports the registrations to the RMI. OPTIONAL.
- export_registrations parameter:
enables to export the registrations to the RMI for lookup.
- port parameter:
Defines the port where to export the registrations.
- LOGGING tag:
This tag exports the traces to the RMI. OPTIONAL.
- access_log_via_rmi parameter:
enables to export the traces to the RMI for lookup.
- rmi_port parameter:
Defines the port where to send the traces.
- log_lifetime parameter:
Defines the life time in seconds of the trace.
- trace_level parameter:
This is an integer that can vary between 0
and 32 (default 0) that controls the amount of log information
written out to the serverLog and debug file
- server_log parameter:
Takes a filename as argument. Use it to catch the message traces in a file.
Use it in conjunction with traceLevel tag
- debug_log parameter:
If you enable debugging, then specify a debugLog file to capture the
debugging messages in the log file. Please send it to us when you encounter a problem.
- bad_message_log parameter:
the file where the bad SIP messages are logged.
- output_proxy parameter:
The output from the proxy, high-level debugging.
- PRESENCE_SERVER tag:
This tag enables the presence server capability. OPTIONAL.
- enable parameter:
enables the presence server capability.
- AUTHENTICATION tag:
This tag enables the authentication capability. OPTIONAL.
Default behavior is disabled.
- enable parameter:
enables the authentication capability.
- method parameter:
takes one argument which can be only Digest.
- class_file parameter:
Use it to upload the class file and process when a message comes in.
One is provided: examples.proxy.authentication.DigestServerAuthenticationMethod
- passwords_file parameter:
The user/passwords XML file for authenticating messages.
- REGISTRATIONS tag:
This tag enables the registrations uploading capability. OPTIONAL.
- enable parameter:
enables the registrations uploading capability.
- registrations_file parameter:
Use it to define the registrations file.
- EXTENSION_HANDLERS tag:
This tag enables you to overwrites or defines new classes for processing new
methods. OPTIONAL.
- METHOD tag:
This tag enables you to overwrites or defines ONE classe for processing the new
method.
- method_name parameter:
Set the new method name you want to process.
- handler_class parameter:
Use it to upload the class file.
4. The XML registration file
The XML file where to define the registrations to upload to the regsitrar. Here are a description of each of
the parameters that you can set up. An example "registrations.xml" is given in the configuration directory.
- REGISTRATION tag:
This tag defines one registration.
- userName parameter:
Use it to define the name of the user to register. OPTIONAL.
- url parameter:
Defines the SIP URL used to store the registration. MANDATORY.
- CONTACT tag:
At least one tag is mandatory.
- url parameter:
Use it to define the contact SIP URL of the user. MANDATORY.
- expires parameter:
Use it to define the time (in sec) of this registration. OPTIONAL.
- DOMAIN tag:
This tag defines the registration related to other proxies. The proxy will
send a REGISTER to the host:port specified by this tag. (The contact address
will be the stack IP address, and the To header will be the "stack_domain" parameter
that has to be specified in the stack tag of the configuration.)
- host_name parameter:
The host to register to.
- port parameter:
The port parameter for this host.
5. The XML authentication file
The XML file where to define the user/password for a certain realm. Here are a description of each of
the parameters that you can set up. An example "passwords.xml" is given in the configuration directory.
- AUTHENTICATION tag:
This tag defines the authentication process. MANDATORY.
- realm parameter:
Use it to define the realm to authenticate. MANDATORY.
- USER tag:
As many tags as you want.
- name parameter:
Use it to define the name of the user to authenticate. MANDATORY.
- password parameter:
Use it to define the password for this user. MANDATORY.
6. Start the proxy
- Change to the proxy directory (examples/proxy).
- Edit the configuration file
(examples/proxy/configuration/configuration.xml).
-
Use the makefile (targeted for Linux/Cygwin) provided in this directory
to start the proxy.
The command to execute is: make proxy .
This command will start the JAVA process:
java -Djava.security.policy=./configuration/policy \
examples.proxy.Proxy -cf ./configuration/configuration.xml
.
- If you prefer to use the GUI to start the proxy,
then the command to execute is: make proxygui .
7. Build Instructions
You can rebuild the proxy using the command: make all
in case you wish to modify the source.
Please report bugs