Difference between revisions of "Using Repro"

From reSIProcate
Jump to navigation Jump to search
(Add TLS testing instructions)
Line 199: Line 199:
  
 
=== Setting Up Repro for TLS ===
 
=== Setting Up Repro for TLS ===
#  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 https://www.resiprocate.org/Certificates
+
#  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 https://www.resiprocate.org/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.
 
#  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
 
#  Enable tls transport on command line: --tls=5061
 
#  Ensure you tell repro what your tls domain is on the command line:  -t=<tlsFQDN>.  If you require multiple TLS domains and transports use the -i command line option (see above).
 
#  Ensure you tell repro what your tls domain is on the command line:  -t=<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>
 
#  The tls domain should also be added to the Domain list, either via the HTTP gui or command line option: -d=<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)".
  
 
=== Configuring DNS ===
 
=== Configuring DNS ===

Revision as of 19:06, 13 March 2011

Getting the Software

Running 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:

%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
 --reqChainName=STRING                                 name of request chain (default: default)
 --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.)
 --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.
 -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

Installing

Installing on Windows

After Getting the Software just run the installation file following the installer instructions.

Installing on Linux OS or Unix-Like Systems

Repro is avaliable both as a RPM build and as a source code.

To install the rpm version run: $ rpm -i <repro_rpm_file>

To install from source code:

  • decompress the source code file
  • cd into the directory
  • run: $ ./configure
  • run: $ make install-repro

Configuring repro using the Web Admin

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>:<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.

File:Repro-login.png

Setting Up Admin Account

Adding Users

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 File:Repro-addUser.png


Adding Routes to Gateways

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.

File:Repro-addRoute.png

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.

File:Repro-showRoutes.png

See Common_rePro_Routes 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.

Configuring the Address Control List

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.

File:Repro-ACLs.png

Configuring SIP user agents to work with repro

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

The values for these parameters assuming the above examples for domain and user would be as follows:

User Address of Record: sip:alicedoe@example.com Proxy: example.com User Authorization Id: alicedoe User Password: 1234

Setting Up Repro for TLS

  1. 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 https://www.resiprocate.org/Certificates. Note: see the --cert-path option.
  2. 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.
  3. Enable tls transport on command line: --tls=5061
  4. Ensure you tell repro what your tls domain is on the command line: -t=<tlsFQDN>. If you require multiple TLS domains and transports use the -i command line option (see above).
  5. The tls domain should also be added to the Domain list, either via the HTTP gui or command line option: -d=<tlsFQDN>
  6. 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)".

Configuring DNS

Setting up multiple domains

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".

File:Repro-domains.png

Configuring Logging

(this should be a pointer to the resip docs)

Setting up Repro to be an Edge Server

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> -> the SIP domain that this edge proxy operates under
  • -r sip:<fqdn or IP address of repro server> -> to be used in Record-Route headers
  • -R sip:<domain name or ip address of next-hop for requests in our 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


Troubleshooting

  1. Running Repro on the same machine as a User Agent
  2. Ensuring that repro can proxy SUBSCRIBE and PUBLISH requests