Using Repro
Run the executable from the command line. A number of command line options are available. For a summary of options run repro with the help option:
See the discussion page
WARNING: The command line options interface discussed on this page has been updated to a config file format.
While the information here is mostly valid, the specific command line option formats information needs to be updated.
For information on the newer config file format, please check out the following document:
> ./repro --help
Usage: repro [OPTION...]
-l, --log-type=syslog|cerr|cout where to send logging messages (default: "cout")
-v, --log-level=STACK|DEBUG|INFO|WARNING|ALERT specify the default log level (default: "INFO")
--db-path=STRING path to databases (default: "./")
-r, --record-route=sip:example.com specify uri to use as Record-Route
--force-record-route force record-routing
--assume-path assume path option
--Udp=5060 listen on UDP port (default: 5060)
--tcp=5060 listen on TCP port (default: 5060)
-t, --tls-domain=example.com act as a TLS server for specified domain
--tls=5061 add TLS transport on specified port (default: 5061)
--dtls=0 add DTLS transport on specified port (default: 0)
--enable-cert-server run a cert server
-c, --cert-path=STRING path for certificates (default: "C:\sipCerts" or
"$(HOME)/.sipCerts")
--enable-v6 enable IPV6
--disable-v4 disable IPV4
--disable-auth disable DIGEST challenges
--disable-auth-int disable auth-int DIGEST challenges
--reject-bad-nonces Send 403 if a client sends a bad nonce in their credentials
(will send a new challenge otherwise)
--disable-web-auth disable HTTP challenges
--disable-reg disable registrar
--disable-identity disable adding identity headers
-i, --interfaces=sip:10.1.1.1:5065;transport=tls;tls=tlsdomain.com specify interfaces to add transports to
-d, --domains=example.com,foo.com specify domains that this proxy is authorative
-R, --route=sip:p1.example.com,sip:p2.example.com specify where to route requests that are in this proxy's domain
--http=5080 run HTTP server on specified port (default: 5080)
--http-hostname=STRING http hostname for this server (used in Identity headers)
--recursive-redirect Handle 3xx responses in the proxy
--q-value Enable sequential q-value processing
--q-value-behavior=STRING Specify forking behavior for q-value targets:
FULL_SEQUENTIAL,
EQUAL_Q_PARALLEL, or
FULL_PARALLEL
--q-value-cancel-btw-fork-groups Whether to cancel groups of parallel forks after the period
specified by the --q-value-ms-before-cancel parameter.
--q-value-wait-for-terminate-btw-fork-groups Whether to wait for parallel fork groups to terminate before
starting new fork-groups.
--q-value-ms-between-fork-groups=INT msec to wait before starting new groups of parallel forks
--q-value-ms-before-cancel=INT msec to wait before cancelling parallel fork groups
-e, --enum-suffix=e164.arpa specify enum suffix to search
-b, --allow-bad-reg allow To tag in registrations
-p, --parallel-fork-static-routes parallel fork to all matching static routes and (first batch)
registrations
--timer-C=180 specify length of timer C in sec (0 or negative will disable
timer C)
-a, --admin-password= set web administrator password
--disable-outbound disable outbound support (RFC5626)
--outbound-version=INT set the draft version of outbound to support (default: 11/RFC5626)
--enable-flow-tokens enable use of flow-tokens in non-outbound cases (This is a
workaround, and it is broken. Only use it if you have to.)
--nat-detection-mode=STRING enable use of flow-tokens in non-outbound cases for clients detected
to be behind a NAT (This is a workaround, and it is broken. Only use
it if you have to.). This a more selective flow token hack mode to
repro for clients not supporting RFC5626. The original flow token
hack (--enable-flow-tokens) will use flow tokens on all client requests.
This may not always be desired. Consider a case where repro is used on
a public IP, has individual UA softphones behind residential NATs (where
flow token use is desired) and is also used to communicate with a peering
provider (such as IP trunking). If the peering provider uses TCP but
disconnects the TCP connection after each request, then using flow tokens
is not desired. Assuming the peering provider is running on a public IP,
this mode can help to selectively enable flow token use. Possible values
are:
DISABLED (default) - do nothing special
ENABLED - Any request to be forwarded will be examined for a difference
between the host in the top via and the source host of the message
(from the IP packet header). If they are different, then we assume
the sending client is behind a NAT and we use double record routing
with flow tokens, to help ensure that messaging for this client uses
the same connection
PRIVATE_TO_PUBLIC - Same as above except we add a check to ensure that the
address in the Via is a private address (ala RFC1918 and RFC4193),
and the source address is a non-private address (public). This allows
us to ignore cases of private-private NAT'ing or false detections,
when an internal (to repro) server behind a load balancer is sending
us requests and using the load balancer address in the Via, instead
of the real of the adapter.
--flow-timer=INT set to greater than 0 to enable addition of Flow-Timer header
to REGISTER responses if outbound is enabled (default: 0)
--xmlrpcport=INT port on which to listen for and send XML RPC messaging (used for
registration sync) - 0 to disable (default: 0)
--regsyncpeer=STRING hostname/ip address of another instance of repro to synchronize
registrations with (note xmlrpcport must also be specified)
--server-text=STRING Value of server header for local UAS responses
--internalepoll Only enabled if OS has epoll support. Enables epoll support for
supporting a large number of TCP/TLS connections.
--eventthread Only enabled if OS has epoll support. Use EventThread for stack.
--override-T1 Override the default value of T1 (you probably should not do this).
-V, --version show the version number
Help options:
-?, --help Show this help message
--usage Display brief usage message
Running the proxy server with the default options is fine. If you are troubleshooting, we recommend that you enable DEBUG level logging:
> ./repro -v DEBUG
After Getting the Software just run the installation file following the installer instructions.
Repro is available both as a package on Debian and Ubuntu, and a Fedora RPM build is expected soon
All Linux/UNIX users can build from source code.
On Debian/Ubuntu:
apt-get install repro
On Fedora 18 or above, make sure you have an RPM building environment (e.g. create ~/.rpmmacros) and do:
rpmbuild -tb resiprocate-1.8.6.tar.gz
and then install the RPM files.
For source build, please see AutotoolsBuild
Once repro is running additional configuration are avalible using the WebAdmin pages. The WebAdmin runs on port 5080 by default, or a specific port if you specified it on the command line with the "--http" command-line option.
To view the pages use any Web Browser and open the url: "<repro_address></repro_address>:<port></port>" i.e. if you are running repro on your local machine and you are using the default web access port just open: "http://localhost:5080/". To Login use the initial username: admin and the password "admin" or use the password that you specified on the command line.
To add users click on the add user page, this page allows you to add users that will be able to use repro. The mandatory fields are the username and the domain. The password is the SIP Digest password
Routes are used by repro to send certain requests to a particular location. The static routes use (POSIX-standard) regular expression to match and rewrite SIP URIs. The screenshot shows an example of sending all requests that consist of only digits in the userpart of the SIP URI to a gateway. Note that to match characters that have a special meaning in regular expression (like a "."), you need to escape these. You can also use variable substitution in the rewrite expression. The string inside the first set of parentheses () is referenced in the rewrite string as $1, the second is $2, etc.
Since it is easy to make mistakes entering regular expressions, you can test your static routes in the Show Routes page. Type in a SIP URI, click Test Route. You should see the rewritten URL below.
See Common rePro Routes and Patterns for some commonly used routes and regular expressions used in routes.
Note: Repro processes all routes and adds ALL matching route destinations to the target route set. The order number will determine the order that the matching destinations will be attempted.
The Address Control List allows you to add trusted nodes that will not require any authentication. Identification of the node is done using the incoming address (masks allowed) or Tls peer name. Note: If hostnames or FQDN's are used then a TLS transport type is assumed. All other transport types must specify ACLs by address. To add a trusted node open the ACLs page under configure menu and edit the address and port boxes then click add button.
Configure a SIP user agent (softphone or appliance) with the same user information entered for the user in the rePro configuration interface. The address of record (AOR) for the user will be sip:user-name@repro-domain where the user-name part is the value entered on in the User Name field on the USERS -> ADD USER page. The repro-domain part is the valued entered on the CONFIGURE -> DOMAINS page. Note: you can also see the users' AORs listed on the USERS -> SHOW USERS page. The authentication user id that is expected by rePro is the user-name part of the AOR (no @ or domain name). The parameters for your specific user agent may be labeled differently but typically the following information is required:
- User Address of Record
- Proxy
- User Authorization Id
- User Password
User Address of Record: sip:alicedoe@example.com Proxy: example.com User Authorization Id: alicedoe User Password: 1234
- Please keep in mind that the information below is a little out of date with respect to configuration. See note at the top of this page.
- A domain certificate and private key certificate for the domain FQDN used to reach your repro server must be present in the certificate path. The files must be named as specified in Certificates. Note: see the --cert-path option.
- The certificate must contain the Server Authentication key usage and the tls FQDN in the Subject Common name and/or SubjectAltName (DNS) fields. Note: If multiple names can be used to reach this server, they can be added to the SubjectAltName field.
- Enable tls transport on command line: --tls=5061
- Ensure you tell repro what your tls domain is on the command line: -t=<tlsfqdn></tlsfqdn>. If you require multiple TLS domains and transports use the -i command line option (see above).
- The tls domain should also be added to the Domain list, either via the HTTP gui or command line option: -d=<tlsfqdn></tlsfqdn>
- The openssl package can be used to test your repro instance. Assuming repro is listening on HOST:PORT and has been configured to provide a certificate (you've provided both domain_cert_*.pem and domain_key_*.pem) and that you are not requiring client certs, then run:
openssl s_client -connect HOST:PORT -tls1 -CAfile ROOTPEM
where ROOTPEM is the root cert of your CA (whatever cert with which your client will be configured in order to validate the repro cert), and HOST:PORT is repro's listening port (e.g., -i option). If everything is good, it should report "Verify return code: 0 (ok)".
You must add at least one "domain" before you can use the proxy server. The domains are names that the proxy recognizes after the at-sign (@) in the SIP URI. The list of domains is used by the proxy and the registrar to decide if repro is responsible for SIP requests it receives. The WebAdmin also uses the list of domains to make sure users you add are in one of the domains.
For example, if you want the proxy to answer requests for atlanta.com, you need to add atlanta.com to the list of domains. You still need to make sure that you configure DNS so that SIP requests for that domain resolve to repro.
If you don't have a fully qualified domain name, you can use your IP address as a "domain".
NOTE: TLS Port is currently not used.
WARNING: repro must be restarted after adding domains here.
(this should be a pointer to the resip docs)
Since repro supports, TCP, TLS and RFC5626 it is an excellent choice to be used as an edge proxy to add RFC 5626 (Outbound) support to any PBX/Registrar, or for any other reason. The following command line options should be used when configuring repro as an edge proxy that supports "outbound":
- -d <sipdomainname></sipdomainname> -> the SIP domain that this edge proxy operates under
- -r sip:<fqdn></fqdn> -> to be used in Record-Route headers
- -R sip:<domain></domain>;lr -> Note the ;lr parameter is important to ensure that the request-uri is unaltered as requests pass through this edge
- --disable-reg -> to disable the built-in registrar in repro
- --disable-auth -> to disable digest-challenges if authentication is handled by next hop (optional)
- --http=0 -> to disable the built in HTTP configuration server (optional)
- --assume-path -> only required if the clients using this edge do not have RFC5626 support
- --enable-flow-tokens -> only required if the clients using this edge do not have RFC5626 support
A number of repro features require Record-Routing to be enabled, these include:
- RFC5626 flow routing.
- The --assume-path option.
- The --force-record-routing option.
- The --enable-flow-tokens option
- The --nat-detection-mode option
- -r command line option - this should be used when proper RFC3263 DNS routing is deployed. The record-route should be set to a FQDN that maps correctly on all interfaces/sides of the proxy.
- Specify a specific record-route per interface. The -i command line option must be used. The customer parameter ;rr is used to specify the interface specific record-route. If no specific value is specified, then the transport/interface parameters are used to form the record-route URI. If you need to specify a parameter on the record-route (such as ;transport), then you must encode the ';' as %3b.
Examples:
A. -i "sip:192.168.1.200:5060;transport=tcp;rr=sip:example.com%3btransport=tcp,sip:192.168.1.200:5060;transport=udp;rr=sip:example.com%3btransport=udp"
Defines 2 transports:
- TCP: 192.168.1.200:5060 using Record-Route: sip:example.com;transport=tcp
- UDP: 192.168.1.200:5060 using Record-Route: sip:example.com;transport=udp
B. -i "sip:192.168.1.200:5061;transport=tls;tls=example.com;rr,sip:192.168.1.200:5060;transport=udp;rr"
Defines 2 transports:
- TLS: 192.168.1.200:5061 using Record-Route: sip:example.com
- UDP: 192.168.1.200:5060 using Record-Route: sip:192.168.1.200:5060;transport=udp
Repro keeps an in-memory database of all active registrations. This database is updated when a new SIP Registration message arrives that modifies a particular registration (ie. new registration, registration update, or registration removal). When repro is started it attempts to get a complete copy of the in-memory registration database from the configured reg-sync peer. Once this is obtained it receives updates in real-time to ensure the two instances are synchronized. This design supports a setup where there are two proxy servers live at any one time. Clients could then use DNS SRV records to load balance registrations and routing between the two proxies.
Note: resip/repro supports RFC5766 which has a mode that allows clients to request that a proxy only routes messaging down an existing client initiated TCP connection. This type of registration cannot be meaningfully replicated to another proxy, since it will not contain the socket connection. Clients that support this RFC, are required to register with multiple proxies for fault tolerance. For these reasons – repro will not attempt to replicate any registrations that are using RFC5766 (ie. tagged as 'use existing connection only').
If configured for reg-sync, when repro first starts, it will attempt to connect to the RPC port on the paired node to obtain the initial list of currently active registrations. If it is unable to connect to the paired node, then it will assume the node is offline and that no registration information is available. The registration sync process with move to a disconnected state, where it will periodically attempt to connect to the paired node. Once a connection succeeds it will retrieve the entire list of active registrations on the pair node, and then move to the Synchronized state where push synchronization will be used. If we are doing an initial synchronization with active registrations in our local store, then conflicts are resolved by looking at the LastUpdated time of each contact in order to know which record has the latest information.
Once a complete copy of the registration database is obtained, we move to the Synchronized state. In this state the RPC server will send updates to the client whenever they occur in its local store. This way we can be assured that the instances are synchronized in real-time.
Repro will form a TCP connection to its peer node (server). Once connected the client will send an InitialSync xml rpc request in order to retrieve a snapshot of all existing registrations, following this all communication will be one way from the server to the client. The initial and real-time registration update messaging will be sent from the server to the client as XML formatted stream data.
The following data is stored in the InMemoryRegistrationDatabase class and is transported over the wire to the other instance of repro:
- AOR - Address of Record for a particular registration
- Operation - Add/Update or Remove
- Contact List - List of contacts for the AOR
- Contact - URI used to contact this registration instance for the given AOR
- Expires - The time that this registration will expire. In order to avoid requiring that machines have a synchronized clock, this field will be encoded as the number of seconds until the registration will expire.
- Last Update - The time that this registration was last updated. In order to avoid requiring that machines have a synchronized clock, this field will be encoded as the number of seconds since the last update.
- ReceivedFrom - Source IP address and port of the last endpoint to register if 'outbound' is used.
- SipPath - Path header from registration
- Instance - Instance parameter from the contact header
- RegId - Registration Id parameter from the contact header
- Navigation
- Developers
- Packages
- Community