From SIPfoundry sipXecs IP PBX, The Open Source SIP PBX for Linux - Calivia

Introduction

sipX is designed as a distributed system where all its components can run on different hosts connected to the network. In its current release it is optimized as a packaged system that runs on a single host and therefore there are some limitations separating individual components. However, it is a clear objective of the project to achieve full separation of the components, which will hopefully lead to a highly scalable system.

Some functionality, such as editing sipX services settings, editing dial plans, monitoring and restarting sipX services will not work when sipXconfig is installed on a separate machine. These limitations will be gradually removed. (for example see: [XCF-809])

There are couple of reasons why we may want to distributr sipXpbx system among multiple hosts:

• you have system with enough memory to run SIP proxy but not enough to run sipXconfig - in which case you run sipXconfig component on one machine and all the remaining components on another machine
• you want to run media server on another machine than the rest of the sipX services
• you want sipXconfig to replicate configuration data to multiple host to provide for redundant configuration

(Redundant proxy would require replicating registrations which is not handled yet today - see: sipXpbx High Availability)

Steps

• Install sipXpbx on both hosts: primary host will run sipXconfig (and possible other services), secondary host will not run sipXconfig, instead it'll be configured from primary host. (Terms primary and secondary reflect sipXconfig point of view here).
• Edit /etc/sipxpbx/ProcessDefinitions.xml and comment out components that should not be started.
• Edit /etc/sipxpbx/topology.xml.in to inform sipXconfig about the location of secondary host.
• Install certificates to establish secure connectivity between machines.
• Edit Apache configuration file on secondary host to enable remote replication access from primary host.

Editing Process Definitions file

/etc/sipxpbx/ProcessDefinitions.xml is used to determine which of the services (processes) are to be started by an umbrella sipXpbx service. It's format is self explanatory - it's safe to remove services that you do not want to run a given host.

Configuring topology

You have to tell config server where it should replicate configuration data. Standard installation of config server will assume that it is collocated with all the remaining services and it will only send data to local host. You can change this behavior by editing topology file that lists one or more locations with which sipXconfig will establish communication. You can add secondary location by copying the default location element and changing replication and agent URLs. See example below.

 <topology>
   <location id="LocalMachine">
      <component id="CommServer1"  type="comm-server" />         
      <replication_url>
         https://sipx1.sipfoundry.org:${CONFIG_SERVER_HTTPS_PORT}/cgi-bin/replication/replication.cgi
      </replication_url>
      <agent_url>
         https://sipx1.sipfoundry.org:${CONFIG_SERVER_HTTPS_PORT}/cgi-bin/processmonitor/process.cgi
      </agent_url>
   </location>
   
   <!-- add secondary host definition -->
   <location id="SecondaryMachine">
      <component id="CommServer1"  type="comm-server" />         
      <replication_url>
         https://sipx2.sipfoundry.org:${CONFIG_SERVER_HTTPS_PORT}/cgi-bin/replication/replication.cgi
      </replication_url>
      <agent_url>
         https://sipx2.sipfoundry.org:${CONFIG_SERVER_HTTPS_PORT}/cgi-bin/processmonitor/process.cgi
      </agent_url>
    </location>   
 </topology>
 

If you're using 3.1 and the other system is identical except for the domain name, useful for hot-swap systems a.k.a seconard registration server, then add the following sip_domain element to the location element

<location id="LocalMachine">
 <sip_domain>secondary.sipfoundry.com</sip_domain>
  ...

When 3.2 comes out w/HA capability, this will no longer be nec. So technically this feature will be obsolete before it's even released.

Generating and installing certificates

sipXconfig needs to establish a trust relationship with each location in order to replicate data successfully. This is exactly the same process that is used by the browser when you connect to a secure WEB site. sipXconfig will request the certificate associated with each location and it will verify if this certificate can be trusted (has been signed by a trusted certificate authority).

If you use certificates obtained from a Certificate Authority you do not have to do anything special compared to a single host system. Just make sure that you obtain both certificates from the same CA.

You can temporarily set up the system to use self-signed certificates. However, in this case you need to make sure that both of them are signed with the same CA. This is the outline of the process, assuming that you generate certificates on host1:

• generate CA certificate

   gen-ssl-keys.sh --new-ca

• generate host1 and host2 certificate requests - make sure you use the same SIP domain, but different host names

   gen-ssl-keys.sh --csr
   gen-ssl-keys.sh --csr

• sign both certificate requests with the previously generated CA

   gen-ssl-keys.sh --sign host1.csr --ca ca --ca-key ca.key
   gen-ssl-keys.sh --sign host2.csr --ca ca --ca-key ca.key

• install certificate on host 1

   install-cert.sh host1

• copy CA certificate and host2 certificate to host2 and install them

   install-cert.sh host2

In addition to installing certificates, older versions of sipXconfig required that the CA certificate be manually added to the java key store.

• Import the standby machine CA certificate into the Java VM on the local machine using keytool

  export java=`sipx-config --jdk`
  ${java}/bin/keytool -import -keystore ${java}/jre/lib/security/cacerts -file standby-machine-ca.crt
 

Configuring Apache server

Open up permissions on apache configuration on a remote machine to allow ip address of local machine call. There are 3 places where allow clause has to be modified in this file.

...
Allow from 127.0.0.1 ${CONFIG_SERVER_ADDR} ip_address_of_primary_host
...