Deployment

This chapter provides a step by step instruction on how to set up a Sipwise C5 from scratch.

Initial Installation

Prerequisites

For an initial installation of Sipwise C5 , it is mandatory that your production environment meets the following criteria:

Hardware Requirements

Recommended: Dual-core, x86_64 compatible, 3GHz, 4GB RAM, 128GB HDD
Minimum: Single-core, x86_64 compatible, 1GHz, 2GB RAM, 24GB HDD

Supported Operating Systems

Debian 11 (bullseye) 64-bit

Internet Connection

Hardware needs connection to the Internet

Only Debian 11 (bullseye) 64-bit is currently supported as a host system for Sipwise C5 .

It is HIGHLY recommended that you use a dedicated server (either a physical or a virtual one) for Sipwise C5, because the installation process will wipe out existing MySQL databases and modify several system configurations.

Using Sipwise C5 install CD (recommended)

The install CD provides the ability to easily install Sipwise C5 CE/PRO/Carrier, including automatic partitioning and installation of the underlying Debian system.

PRO/Carrier can be installed only with a commercial license. Otherwise a warning about lack of access to Debian repository will be displayed.

You can install the current Sipwise C5 CE version mr11.3.1 using install CD image (checksums: sha1, md5).

The Sipwise C5 install CD automatically takes care of partitioning, any present data will be overwritten! While the installer prompts for the disk that should be used for installation before its actual execution, it’s strongly recommended to boot the ISO in an environment with empty disks or disks that you don’t plan to use for anything else than the newly installed Sipwise C5 system.

When DHCP is available in your infrastructure then you shouldn’t have to configure anything, instead choose DHCP and press enter. If network configuration still doesn’t work as needed a console based network configuration system will assist you in setting up your network configuration. VLANs are also supported at this stage.

Also, you can use Sipwise C5 install CD to boot the Grml (Debian based live system) rescue system, check RAM using a memory testing tool or install plain Debian system for manual installation using Sipwise C5 installer.

Using the Sipwise NGCP installer

Installing the Operating System

You need to install Debian 11 (bullseye) 64-bit on the server. A basic installation without any additional task selection (like Desktop System, Web Server etc.) is sufficient.

Sipwise recommends using the latest Netinstall ISO as installation medium.

If you use other kinds of installation media (e.g. provided by your hosting provider), prepare for some issues that might come up during installation. For example, you might be forced to manually resolve package dependencies in order to install Sipwise C5 . Therefore, it is HIGHLY RECOMMENDED to use a clean Debian installation to simplify the installation process.

If you installed your system using the Debian CDs/DVDs (so neither using Sipwise C5 install CD nor the Debian Netinstall ISO) apt-get might prompt to insert disk to proceed during Sipwise C5 installation. The prompt won’t be visible for you and installation hangs. Please disable the cdrom entries in /etc/apt/sources.list and enable a Debian mirror (e.g. https://deb.debian.org/debian/) instead.

Using special Debian setups

If you plan to install Sipwise C5 on Virtual Hosting Providers like Dreamhost with their provided Debian installer, you might need to manually prepare the system for Sipwise C5 installation, otherwise the installer will fail installing certain package versions required to function properly.

Using Dreamhost Virtual Private Server

A Dreamhost virtual server uses apt-pinning and installs specific versions of MySQL and apache, so you need to clean this up beforehand.

Apache is not used by default since mr3.6.1, still better to remove pinned Apache version.

apt-get remove --purge mysql-common ndn-apache22
mv /etc/apt/preferences /etc/apt/preferences.bak
apt-get update
apt-get dist-upgrade

Be aware that this step will break your web-based system administration provided by Dreamhost. Only do it if you are certain that you won’t need it.

Installing the Sipwise NGCP

Download and install the latest Sipwise C5 installer package:

PKG=ngcp-installer-mr11.3.1.deb
wget http://deb.sipwise.com/spce/${PKG}
dpkg -i ${PKG}

Run the installer as root user:

ngcp-installer

You can find the previous versions of Sipwise C5 installer package here.

The installer will ask you to confirm that you want to start the installation. Read the given information carefully, and if you agree, proceed with y.

The installation process will take several minutes, depending on your network connection and server performance. If everything goes well, the installer will (depending on the language you use), show something like this:

Installation finished. Thanks for choosing Sipwise C5 Community Edition.
Please reboot the server to continue with the configuration.

Be aware that all services will be disabled. If you need a specific service - re-enable it when the initial configuration is done.

During the installation, you can watch the background processing by executing the following command on a separate console:

tail -f /var/log/ngcp-installer.log

Initial Configuration

After the installation has finished successfully and the server gets rebooted it is necessary to perform the initial configuration:

It is strongly recommended to run ngcp-initial-configuration within terminal multiplexer like screen.

screen -S ngcp
ngcp-initial-configuration

The tool will ask you to confirm the network configuration which is based on the current one. Read carefully the information printed on screen, and if you agree, proceed by typing y. If you want to change these parameters, you can edit the file /etc/ngcp-installer/config_deploy.inc and adjust the variables with the desired values.

If everything goes well, you should see the message:

System was successfully configured, now you have the best VoIP software.

Using a pre-installed virtual machine

For quick test deployments, pre-configured virtualization images are provided. These images are intended to be used for quick test, not recommended for production use.

Vagrant box for VirtualBox

Vagrant is an open-source software for creating and configuring virtual development environments. Sipwise provides a so called Vagrant base box for your service, to easily get direct access to your own Sipwise C5 Virtual Machine without any hassles.

The following software must be installed to use Vagrant boxes: VirtualBox v.5.2.26+ and Vagrant v.2.2.3+.

Get your copy of Sipwise C5 by running:

vagrant init spce-mr11.3.1 https://deb.sipwise.com/spce/images/mr11.3.1/sip_provider_CE_mr11.3.1_vagrant.box
vagrant up

As soon as the machine is up and ready you should have your local copy of Sipwise C5 with the following benefits:

all the software and database are automatically updated to the latest available version
the system is configured to use your LAN IP address (received over DHCP)
basic SIP credentials to make SIP-2-SIP calls out of the box are available

Use the following command to access the terminal:

vagrant ssh

or login to Administrator web-interface at https://127.0.0.1:1443/ (with default user administrator and password administrator).

There are two ways to access VM resources, through NAT or Bridge interface:

a.b.c.d is IP address of VM machine received from DHCP; x.y.z.p is IP address of your host machine

Table 1. Vagrant based VirtualBox VM interfaces:
Description	Host-only address	LAN address	Notes
SSH	ssh://127.0.0.1:2222	ssh://a.b.c.d:22 or ssh://x.y.z.p:2222	Also available via "vagrant ssh"
Administrator interface	https://127.0.0.1:1443/	https://a.b.c.d:1443/ or https://x.y.z.p:1443/
New Customer self care interface	https://127.0.0.1:1443	https://a.b.c.d:1443 or https://x.y.z.p:1443	new self-care interface based on powerful ngcp-panel framework
Old Customer self care interface	https://127.0.0.1:22443	https://a.b.c.d:443 or https://x.y.z.p:22443	will be removed in upcoming releases
Provisioning interfaces	https://127.0.0.1:2443	https://a.b.c.d:2443 or https://x.y.z.p:2443
SIP interface	not available	sip://a.b.c.d:5060	Both TCP and UDP are available.

VM ports smaller then 1024 mapped to ports 22<vm_port> through NAT, otherwise root on host machine requires to map them. It means SSH port 22 mapped to port 2222, WEB port 443 → 22443.

VM IP address (a.b.c.d), as well as SIP credentials will be printed to terminal during "vagrant up" stage, e.g.:

[20_add_sip_account] Adding SIP credentials...
[20_add_sip_account]   - removing domain 192.168.1.103 with subscribers
[20_add_sip_account]   - adding domain 192.168.1.103
[20_add_sip_account]   - adding subscriber 43991002@192.168.1.103 (pass: 43991002)
[20_add_sip_account]   - adding subscriber 43991003@192.168.1.103 (pass: 43991003)
[20_add_sip_account]   - adding subscriber 43991004@192.168.1.103 (pass: 43991004)
[20_add_sip_account]   - adding subscriber 43991005@192.168.1.103 (pass: 43991005)
[20_add_sip_account]   - adding subscriber 43991006@192.168.1.103 (pass: 43991006)
[20_add_sip_account]   - adding subscriber 43991007@192.168.1.103 (pass: 43991007)
[20_add_sip_account]   - adding subscriber 43991008@192.168.1.103 (pass: 43991008)
[20_add_sip_account]   - adding subscriber 43991009@192.168.1.103 (pass: 43991009)
[20_add_sip_account] You can USE your VM right NOW:  https://192.168.1.103:1443/

To turn off your Sipwise C5 virtual machine, type:

vagrant halt

To completely remove Sipwise C5 virtual machine, use:

vagrant destroy
vagrant box remove spce-mr11.3.1

Further documentation for Vagrant is available at the official Vagrant website.

Vagrant usage tips:

Default SSH login is root and password is sipwise. SSH connection details can be displayed via:

  vagrant ssh-config

VirtualBox Guest Additions is installed by default but disabled. Enable it to use Vagrant Synced Folders feature. Execute the following commands inside VM:

  systemctl start vboxadd-service.service vboxadd.service
  ngcpcfg set /etc/ngcp-config/config.yml "systemd.custom_preset=['vboxadd-service.service', 'vboxadd.service']"
  ngcpcfg apply "Start VirtualBox Guest Additions on boot"

You can download a Vagrant box for VirtualBox from here manually (checksums: sha1, md5).

VirtualBox image

You can download a VirtualBox image from here (checksums: sha1, md5). Once you have downloaded the file you can import it to VirtualBox via its import utility.

The format of the image is ova. If you have VirtualBox 3.x running, which is not compatible with ova format, you need to extract the file with any tar compatible software and import the ovf file which is inside the archive.

On Linux, you can do it like this:

tar xvf sip_provider_CE_mr11.3.1_virtualbox.ova

On Windows, right-click on the ova file, choose Open with and select WinZIP or WinRAR or any other application able to extract tar archives. Extract the files to any place and import the resulting ovf file in VirtualBox.

Considerations when using this virtual machine:

You will need a 64bit guest capable VirtualBox setup.
The root password is sipwise
You should use bridge mode networking (adjust your bridging interface in the virtual machine configuration) to avoid having Sipwise C5 behind NAT.
You’ll need to adjust your timezone and keyboard layout.
The network configuration is set to DHCP. You’ll need to change it to the appropriate static configuration.
As the virtual image is a static file, it won’t contain the most updated versions of our software. Please upgrade the system via apt as soon as you boot it for the first time.

VMware image

You can download a VMware image from here (checksums: sha1, md5). Once you have downloaded the file, extract the zip file and copy its content to your virtual machines folder.

Considerations when using this virtual machine:

You will need a 64bit guest capable vmware setup.
The root password is sipwise
You’ll need to adjust your timezone and keyboard layout.
The network configuration is set to DHCP. You’ll need to change it to the appropriate static configuration.
As the virtual image is a static file, it won’t contain the most updated versions of our software. Please upgrade the system via apt as soon as you boot it for the first time.

Amazon EC2 image

Sipwise provides AMI (Amazon Machine Images) images in several Amazon EC2 regions for the supported Sipwise C5 releases only. Please find the appropriate AMI ID for your region in release announcement.

If the release is out of support you can still find AMI image for it but only in one region - eu-central-1

The current documentation will use Amazon region eu-central-1 with AMI ID ami-0868999d7ba41b562 as an example. Please find the appropriate AMI ID for your region in the latest release announcement.

If you want to use Sipwise C5 AMI image in one of the regions where it’s not available, you can create your own private AMI image based on the one provided by Sipwise.

You can create your private image in any region following these steps

Go to eu-central-1 region with your EC2 account.
Find Sipwise AMI image for the release you want. You can get AMI image id from release notes for that specific release.
Launch temporary VM instance with that image.
Right-click the instance and choose Create Image from the context menu.
In the Create Image dialog box, type a unique name and description, and then choose Create Image.
It may take a few minutes for the AMI to be created. After it is created, it will appear in the AMIs view in AWS Explorer.
Stop and destroy temporary VM.
Select the AMI you’ve just created and choose Actions, Copy AMI.
On the Copy AMI page set Destination Region to the region of your choice.
Choose Copy AMI.
Now you can find the AMI image copied to a region of your choice.
The initial status of the new AMI is Pending. The AMI copy operation is complete when the status is Available.
Now you can use your own image and follow the steps from example below to launch Sipwise C5 instance in the region of your choice.

For more details please follow the official Amazon AWS documentation about how to create and copy AMI images.

As a next step please visit https://console.aws.amazon.com/ec2/v2/home?region=eu-central-1 with your EC2 account.

Choose "Launch Instance":

Figure 1. Launch Amazon EC2 Instance for your region

Select "Community AMIs" option, enter "ami-0868999d7ba41b562" inside the search field and press "Select" button:

Choose an installation image (different for each region)

Figure 2. Choose an image (different for each region)

Select the Instance Type you want to use for running Sipwise C5 (recommended: >=4GB RAM):

Figure 3. Choose Amazon EC2 instance

Do not forget to tune necessary Sipwise C5 performance parameters depending on Amazon EC2 instance type and performance you are looking for. Find more information about Sipwise C5 performance tuning in security-performance:security-performance.adoc#requirements-and-performance.

Run through next configuration options

Configure Instance: optional (no special configuration required from Sipwise C5)
Add Storage: choose >=8GB disk size (no further special configuration required from Sipwise C5)
Tag Instance: optional (no special configuration required from Sipwise C5)
Configure Security Group: create a new security group, using the following rules:
- TCP port 22 (SSH)
- TCP port 443 (HTTPS/CSC)
- TCP port 1443 (Admin Panel)
- TCP port 5060 (SIP/TCP)
- UDP port 5060 (SIP/UDP)
- TCP port 5061 (SIP/TLS)
- TCP port 5222 (SIP)
- TCP port 5269 (SIP)
- UDP port 30000:44999 (RTP)

Please feel free to restrict the 'Source' options in your Security Group to your own (range of) IP addresses, especially for SSH and Admin Panel!

Figure 4. Configure Security Group

Finally review instance in the last step (Review Instance Launch) and press Launch button.

Choose an existing key pair which you want to use for logging in, or create a new one if you don’t have one.

Figure 5. Choose a key pair to access the system

You should have a running instance after a few seconds/minutes now (check DNS name/IP address).

Figure 6. Running Amazon EC2 Sipwise NGCP instance

First step should be logging in to the Admin panel (username administrator, password administrator) and changing the default password: https://$DNS:1443/ and then follow security-performance:security-performance.adoc#security to secure your installation.

Logging in via SSH should work now, using the key pair name (being sip-provider-ce.pem as $keypair in our example) and the DNS name/IP address the system got assigned.

ssh -i $keypair.pem admin@$DNS

Now you can increase your privileges to user root for further system configuration:

sudo -s

Don’t forget to add the Advertised IP for kamailio lb instance, since it’s required by the Amazon EC2 network infrastructure:

ngcp-network --set-interface=eth0 --advertised-ip=<your_public_amazon_ip>

and apply your changes:

ngcpcfg apply 'add advertised-ip on interface eth0'

Now feel free to use your newly started Amazon EC2 Sipwise C5 instance!

Do not forget to stop unnecessary instance(s) to avoid unexpected costs (see https://aws.amazon.com/ec2/pricing/).

Initial System Configuration

After the configuration you are ready to adjust the system parameters to your needs to make the system work properly.

Network Configuration

If you have only one network card inside your system, its device name is eth0, it’s configured and only IPV4 is important to you then there should be nothing to do for you at this stage. If multiple network cards are present, your network card does not use eth0 for its device name or you need IPv6 then the only parameter you need to change at this moment is the listening address for your SIP services.

To do this, you have to specify the interface where your listening address is configured, which you can do with the following command (assuming your public interface is eth0):

ngcp-network --set-interface=eth0 --ip=auto --netmask=auto --hwaddr=auto
ngcp-network --move-from=lo --move-to=eth0 --type=web_ext --type=sip_ext --type=rtp_ext --type=ssh_ext --type=web_int

If you want to enable IPv6 as well, you have to set the address on the proper interface as well, like this (assuming you have an IPv6 address fdda:5cc1:23:4:0:0:0:1f on interface eth0):

ngcp-network --set-interface=eth0 --ipv6='FDDA:5CC1:23:4:0:0:0:1F'

Always use a full IPv6 address with 8 octets. Leaving out zero octets (e.g. FDDA:5CC1:23:4::1F) is not allowed.

You should use the IPv6 address in upper-case because LB (kamailio) handles the IPv6 addresses internally in upper-case format.

Check or adjust the network configuration in the /etc/ngcp-config/network.yml file.

editor /etc/ngcp-config/network.yml

The following configuration shows NGCP running in the internal 192.168.0.0/24 network behind the NAT:

...
  self:
    eth0:
      dns_nameservers:
      - 192.168.0.1
      hwaddr: 11:22:33:44:55:66
      ip: 192.168.0.10
      gateway: 192.168.0.1
      netmask: 255.255.255.0
      type:
      - ssh_ext
      - web_ext
      - web_int
      - sip_ext
      - rtp_ext
    interfaces:
    - lo
    - eth0
    lo:
...

Apply the adjusted network configuration, and /etc/network/interfaces will be regenerated from the new configuration.

ngcpcfg apply 'change network configuration'

The resulting /etc/network/interfaces file will look like this:

# File autogenerated by ngcpcfg

# lo ----------------------
auto lo
iface lo inet loopback
# --------------------------------------------

# eth0 ----------------------
auto eth0
iface eth0 inet static
  address 192.168.0.10
  netmask 255.255.255.0
  gateway 192.168.0.1
  dns-nameservers 192.168.0.1
# --------------------------------------------

Reboot the server to apply the new network configuration:

reboot

Apply Configuration Changes

In order to apply the changes you made to /etc/ngcp-config/config.yml, you need to execute the following command to re-generate your configuration files and to automatically restart the services:

ngcpcfg apply 'added network interface'

At this point, your system is ready to serve.

Start Securing Your Server

During installation, the system user cdrexport is created. This jailed system account is supposed to be used to export CDR files via sftp/scp. Set a password for this user by executing the following command:

passwd cdrexport

The installer has set up a MySQL database on your server. You need to set a password for the MySQL root user to protect it from unauthorized access by executing this command:

mysqladmin password <your mysql root password>

For the Administrative Web Panel located at https://<your-server-ip>:1443/, a default user administrator with password administrator has been created. Connect to the panel (accept the SSL certificate for now) using those credentials and change the password of this user by going to Settings→Administrators and click the Edit when hovering over the row.

Configuring the system-wide editor

The default editor is set to nano on the system. If you prefer a different editor, make sure it’s installed and set the default editor via:

sudo update-alternatives --config editor

if you want to use a specific editor only temporarily, set the EDITOR environment variable instead. For example to run command with the editor set to vim, invoke "EDITOR=vim command".

Configuring the Email Server

The Sipwise C5 installer will install mailx (which has Exim4 as MTA as a default dependency) on the system, however the MTA is not configured by the installer. If you want to use the Voicemail-to-Email feature of the Voicebox, you need to configure your MTA properly. If you are fine to use the default MTA Exim4, execute the following command:

sudoedit /etc/ngcp-config/config.yml  # edit section 'email:' according to your needs
sudo ngcpcfg apply 'adjust exim4 / MTA configuration'

You are free to install and configure any other MTA (e.g. postfix) on the system, if you are more comfortable with that.

Advanced Network Configuration

You have a typical test deployment now and you are good to go, however you may need to do extra configuration depending on the devices you are using and functionality you want to achieve.

What’s next?

To test and use your installation, you need to follow these steps now:

Create a SIP domain
Create some SIP subscribers
Register SIP endpoints to the system
Make local calls and test subscriber features
Establish a SIP peering to make PSTN calls

Please read the next chapter for instructions on how to do this.