High Availability Installations on AWS
This guide provides step-by-step instructions for deploying PortSIP PBX High Availability (HA) in an AWS EC2 environment, ensuring service resilience, automatic failover, and call continuity.
Prerequisites
Before deploying the PortSIP PBX HA cluster, ensure the following requirements are met.
Operating System
Ubuntu 24.04 LTS (64-bit) is required on all PBX nodes.
AWS EC2 Instances
Three AWS EC2 instances are required.
In this guide, the terms EC2 server, PBX server, and node are used interchangeably and all refer to an AWS EC2 instance.
Instance Specifications
Minimum 4 vCPUs
Minimum 4 GB RAM
Higher specifications are recommended for production or high-call-volume environments.
Network Requirements
Public IP Assignment: Enable Assign a public IP automatically when creating each EC2 instance.
Private IP Address: Each EC2 instance must be assigned a static private IP address.
Location: All EC2 instances must be deployed in the same AWS Region, VPC, and subnet.
IP and Storage Resources
Elastic IP (EIP): One Elastic IP address must be allocated.
Elastic Block Store (EBS): A shared EBS volume is required for persistent PBX data.
Working Mechanisms
The PortSIP PBX High Availability (HA) architecture operates through the following mechanisms.
Node Configuration
Three PBX nodes operate concurrently as part of an HA cluster. This quorum-based design prevents split-brain scenarios and ensures reliable failover decisions when switching the active node.
Data Storage
Amazon EBS is used as shared, persistent storage for critical PBX data, including:
Active call state information
Call recording files
Log files
Call Detail Records (CDRs)
User-uploaded prompt and media files
This ensures all PBX nodes have access to the most up-to-date data during failover.
Access Point
An AWS Elastic IP (EIP), a static public IP address serves as the single external access point for the PBX system.
The Elastic IP is always mapped to the currently active PBX node, in this example, it's 54.151.30.9.
The Elastic IP is used by:
IP phones
Desktop and mobile client applications
Web browsers and WebRTC clients
This provides a consistent access address regardless of which node is active.
Status Monitoring
Pacemaker continuously monitors the health and availability of all PBX nodes and cluster resources, detecting failures in real time.
Service Provisioning and Failover
Under normal operation, the active (primary) node provides PBX services.
If the active node becomes unavailable:
Pacemaker immediately relocates the Elastic IP to a healthy standby node.
New service requests are transparently handled by the standby node.
No endpoint reconfiguration is required.
Call Restoration
Any calls that were established on the failed primary node are automatically restored by the standby node, ensuring minimal disruption to ongoing communications.
Notes
All Linux commands in this guide must be executed as the default
ubuntuuser.
Creating the User Group and User
To deploy PortSIP PBX High Availability (HA) on AWS, you must create an IAM user group and IAM user with the appropriate permissions.
Create an IAM User Group
Open the AWS IAM Console.
Choose one of the following:
Select an existing user group, or
Click Create group to create a new user group.
Assign the required permission policies to the group.
Required Permission Policies
The IAM user group must include the following permission policies:
AmazonEC2FullAccess
AmazonEBSCSIDriverPolicy
These policies allow the HA cluster to manage EC2 instances, Elastic IPs, and EBS volumes during failover operations.
Example Configuration
As shown in the screenshot below, you may name the group hagroup and ensure the following policies are attached:
AmazonEC2FullAccess
AmazonEBSCSIDriverPolicy
Verify that both policies are attached before proceeding to create the IAM user.
Create User
To create a new IAM user, follow these steps:
Open the AWS IAM Console.
Click Users to view the list of existing users.
Click Create user to start the user creation process.
Enter a user name (for example,
hauser).Assign this user to the previously created user group
hagroup.
As shown in the screenshot below, the user hauser should be associated with the hagroup, ensuring it inherits the required permissions for deploying and managing the PortSIP PBX HA cluster.
Create User Access Key
After successfully creating the IAM user, follow the steps below to create an access key for the user (for example, hauser).
In the AWS IAM Console, select Users and choose the user
hauser.Click Create access key.
In Step 1, under Access key best practices & alternatives, select Command Line Interface (CLI) as the use case.
Continue to Step 3, Retrieve access keys. Here, it's crucial to note and save the Access key and Secret access key for future use.
❗Important Make sure to securely save both the Access key ID and the Secret access key. These credentials are required for configuring AWS CLI access on the PBX servers and cannot be retrieved again after this step.
Once the access key is created and saved, you can proceed with configuring AWS CLI credentials on the PortSIP PBX HA nodes.
VPC and Subnet
VPC
In the PortSIP PBX High Availability (HA) deployment, all PBX nodes must be deployed within the same AWS Availability Zone, VPC, and subnet. This is a strict requirement to ensure reliable failover, shared storage access, and consistent network behavior.
In this example, the deployment uses the us-west-1 Region.
To configure the VPC:
Open the AWS VPC Console.
Use the default VPC (you may also create a new VPC if required).
Verify the IPv4 CIDR block.
As shown in the screenshot below, the example VPC uses the following IPv4 CIDR:
VPC IPv4 CIDR:
172.31.0.0/16
Each PBX node must be assigned a static private IP address from the subnet within this VPC.
Create the Subnet
To create or verify the subnet configuration, follow these steps:
In the AWS VPC Console, click Subnets.
If no suitable subnet exists, click Create subnet to create a new one.
Select the VPC created or chosen in the previous step.
Configure the subnet settings.
In the example shown below:
Subnet ID:
subnet-8cadc4e8IPv4 CIDR:
172.31.16.0/20Availability Zone:
us-west-1c
❗Important The subnet CIDR block must be
/20. Using any other CIDR size will cause the PortSIP PBX HA installation to fail.
In this deployment scenario, the following static private IP addresses are assigned to the PBX nodes:
Node 1:
172.31.16.133Node 2:
172.31.16.134Node 3:
172.31.16.135
These IP addresses must be reserved and consistently assigned to each EC2 instance to ensure stable HA operation.
Create Security Group
To create a security group for the PortSIP PBX HA deployment, follow these steps:
Open the AWS EC2 Console.
Navigate to Security Groups to view the existing security groups.
If no suitable security group exists, click Create security group.
Enter a name and description for the security group.
Example Configuration
For example:
Security Group Name:
pbx-haSecurity Group ID:
sg-0e2bea9ea4033f893
This security group will later be configured with the required inbound and outbound rules to allow SIP signaling, media traffic, web access, and HA cluster communication between PBX nodes.
❗ Important The same security group must be configured and attached when creating all PortSIP PBX HA EC2 instances.
Inbound rule
❗ Important For the PortSIP PBX HA cluster to function correctly, ALL TCP and ALL UDP traffic must be allowed within the same subnet.
TYPE
PROTOCOL
PORT RANGE
SOURCE
DESCRIPTION
Custom UDP
UDP
35000 - 65000
0.0.0.0/0
RTP
ALL TCP
TCP
0 - 65535
172.31.0.0/16
ALL UDP
UDP
0 - 65535
172.31.0.0/16
Custom TCP
TCP
5432
172.31.0.0/16
db
SSH
TCP
22
0.0.0.0/0
ssh
Custom UDP
UDP
5060
0.0.0.0/0
pbx sip/udp
Custom TCP
TCP
5061
0.0.0.0/0
pbx sip/tcp
Custom TCP
TCP
5063
0.0.0.0/0
pbx sip/wss
Custom TCP
TCP
8882-8900
0.0.0.0/0
pbx
Custom TCP
TCP
10443
0.0.0.0/0
sbc webrtc
HTTP
TCP
80
0.0.0.0/0
http
HTTPS
TCP
443
0.0.0.0/0
https
Outbound rule
TYPE
PROTOCOL
PORT RANGE
DESTINATION
DESCRIPTION - OPTIONAL
All traffic
All
All
0.0.0.0/0
–
Create EC2 Instances
This section explains how to create the AWS EC2 instances used for the PortSIP PBX High Availability (HA) cluster.
Create EC2 Instance
Follow the steps below to create each EC2 instance.
Application and OS Image (AMI)
In the Application and OS Images (Amazon Machine Image) section:
Select Ubuntu Server 24.04 LTS (HVM), SSD Volume Type
This operating system is required for PortSIP PBX HA deployments.
Instance Type
In the Instance type section:
Select
t3.mediumor another suitable instance type.
You should choose the instance type based on your business requirements, including user scale and call concurrency.
For environments with:
Higher numbers of users
Increased concurrent calls
More CPU cores and memory are required. Refer to the Hardware Specifications documentation when selecting the appropriate instance type.
Create a Key Pair for Login
In the Key pair (login) section:
Select an existing key pair, or
Click Create new key pair to generate a new one.
In this guide, a new key pair named aws-portsip-pbx-ha is created. This action generates a private key file named:
❗ Important All EC2 instances in the PortSIP PBX HA cluster must use the same key pair. Using different key pairs will prevent consistent administrative access and complicate HA management.
Networking
To configure networking for the EC2 instances, follow these steps.
Network Settings
VPC:
vpc-027ba466Subnet:
subnet-8cadc4e8(Created earlier in this guide)Auto-assign public IP: Select Enable
Firewall (Security Groups)
In the Firewall (security groups) section:
Select the existing security group
pbx-hathat was created earlier.
❗ Important All HA EC2 instances must use the same security group to ensure proper cluster communication, failover detection, and service continuity.
Advanced Network Configuration
In Advanced network configuration > Network interface 1:
Set the Primary IP for each EC2 instance as follows:
Node 1:
172.31.16.133Node 2:
172.31.16.134Node 3:
172.31.16.135
❗ Important These static private IP addresses must be assigned exactly as specified. Changing or reassigning these IPs after deployment may cause HA failover failures or service disruption.
Configuring Storage (Volume)
In the Storage (Volumes) section, configure the disk that will be used to install the Linux operating system for the PortSIP PBX HA nodes.
This volume is primarily used for:
The Ubuntu operating system
System packages and runtime dependencies
For most deployments:
40 GB is sufficient for standard environments
100 GB is recommended for larger or long-term production deployments
Choose the disk size based on your operational requirements and future growth plans.
In the Advanced details section, configure Metadata version to V1 and V2 (token optional), as shown in the screenshot below.
❗ Important This storage volume is used only for the operating system and system-level components. PBX data such as recordings, logs, databases, and media files are stored on a separate shared EBS volume, which is configured later in this guide.
Verifying Host Name
By default, AWS automatically assigns a host name to each EC2 instance after it is successfully created. In most cases, no manual host name configuration is required, which simplifies the setup process.
In this deployment scenario, the host names appear as shown in the screenshot below.
NODE
HOST NAME
PUBLIC IP
PRIVATE IP
DISK
DEFAULT USER
1
ip-172-31-16-133
Auto-assign
172.31.16.133
/dev/sda (40GB)
ubuntu
2
ip-172-31-16-134
Auto-assign
172.31.16.134
/dev/sda (40GB)
ubuntu
3
ip-172-31-16-135
Auto-assign
172.31.16.135
/dev/sda (40GB)
ubuntu
Allocate Elastic IP
Next, you need to allocate an Elastic IP (EIP) for the PortSIP PBX HA cluster. This Elastic IP serves as the single public access point for all PBX clients.
Follow these steps:
Open the AWS EC2 Console.
Click Elastic IPs to view the list of allocated Elastic IP addresses.
Click Allocate Elastic IP address to create a new one.
For example:
Elastic IP address:
54.151.30.9Allocation ID:
eipalloc-02c7cf64a5cd449cf. Please note it and will used in the later steps.
Create Elastic Block Store (EBS) Volume
Next, create an Amazon Elastic Block Store (EBS) volume to store shared PBX HA data.
This EBS volume is used to store critical data, including:
Databases (DB)
Call recording files
Log files
Call reports
Chat and media files
Because this volume holds all tenant and call data, it should be sized generously, especially in production environments.
Recommended Volume Size
Production environments: 1000 GB or larger
Adjust sizing based on:
Call volume
Recording retention period
Chat and media usage
Create the EBS Volume
To create the EBS volume:
In the AWS EC2 Console, click Volumes.
Click Create volume.
Configure the volume settings.
For example, the volume configuration may look like this (as shown in the screenshot below).
io2
vol-0e06e1e9da3c49b67
1000GB
500
us-west-1c
No
No
The following screenshot shows the example:
Configuring AWS
This section describes how to install and configure the AWS CLI and prepare the required credentials and key files on the PortSIP PBX HA nodes.
Install AWS CLI
Install the AWS CLI v2 on all EC2 instances in the HA cluster.
Run the following commands on each EC2 instance:
After installation, verify the AWS CLI version:
Configuring AWS IAM
Before running the configuration, determine the AWS Region where your EC2 instances are deployed.
In this example, the region is us-west-1 (as shown in the AWS console screenshot).
Run the following command on all EC2 instances:
When prompted, enter the following information:
AWS Access Key ID [None]: Enter your Access Key ID (see Create User Access Key).
AWS Secret Access Key [None]: Enter your Secret Access Key.
Default region name [None]: Enter the AWS region (for example,
us-west-1).Default output format [None]: Enter
json.
Configuring the Certificate (Key Pair) File
You must upload the EC2 key pair file to the primary node for SSH access between HA nodes.
In this guide, the key pair file is: aws-portsip-pbx-ha.pem
Upload this file to the following directory on the node with IP address 172.31.16.133:
After uploading the file, set the correct permissions. Run the following command only on node 172.31.16.133:
❗ Important This step must be performed only on the primary node (172.31.16.133). Incorrect file permissions or missing key files will prevent secure SSH communication required for HA operations.
Configuring PortSIP PBX HA
This section describes how to download the required HA resources and prepare the configuration variables for deploying the PortSIP PBX HA cluster.
Download the PBX Resource Package
The following commands must be executed only on the EC2 instance with the private IP address 172.31.16.133.
Run the commands below to download and extract the PortSIP PBX HA resource package:
Set Variables
Before proceeding with the HA deployment, prepare values for the required configuration variables.
pbx01_instance_id
string
The instance id of the node 1
pbx02_instance_id
string
The instance id of the node 2
pbx03_instance_id
string
The instance id of the node 3
eip_allocation_id
string
Elastic Allocation ID. In this example is eipalloc-02c7cf64a5cd449cf
ebs_volume_id
string
EBS Volume ID
pbx_image
string
PortSIP PBX docker image
ssh_private_key_file
string
The path of certificate file for the key pair "aws-portsip-pbx-ha"
The following commands must be executed only on the EC2 instance with the private IP address 172.31.16.133.
Install Dependencies
The following commands must be executed only on the EC2 instance with the private IP address 172.31.16.133.
Deploying PBX HA
Deploy the HA Cluster
The following command must be executed only on the EC2 instance with the private IP address 172.31.16.133.
Run the command below to start deploying the PortSIP PBX HA cluster:
❗ Important The deployment process may take a significant amount of time to complete. Do not interrupt the process, and do not restart or shut down the EC2 instance while the deployment is in progress. Interrupting the process may result in an incomplete or corrupted HA deployment.
Accessing the PBX After Deployment
Once the resource configuration and deployment are completed successfully, you can access the PortSIP PBX Web Portal by opening the following URL in a web browser: https://54.151.30.9:8887
From this point forward:
All PBX management, configuration, and administration will be performed via the Elastic IP
54.151.30.9.SIP clients, applications, and web access will continue to use this Elastic IP, regardless of which HA node is active.
You may also configure your web domain to resolve to this Elastic IP if you prefer to access the PBX using a domain name instead of an IP address.
Configuring PortSIP PBX
When you sign in to the PBX Web Portal, the Setup Wizard will automatically appear.
Step 1: Network Environment
In the first step of the wizard, configure the network settings as follows:
Private IPv4: Enter the private virtual IP
54.151.30.9.Public IPv4: Enter the Elastic IP
54.151.30.9.
Step 2: SSL Certificate
To enable TLS transport for SIP and secure HTTPS access to the Web Portal and REST API, an SSL certificate must be configured.
Domain Setup
You need a domain name that points to your PBX server IP address. For example, you may purchase a domain from providers such as GoDaddy and configure its DNS records accordingly.
SSL Certificate Requirements
A trusted SSL certificate is strongly recommended to avoid browser security warnings. Common certificate providers include DigiCert, GeoTrust, GoDaddy, and others.
If you do not have a trust domain or SSL certificate, you may:
Use the PBX IP address as the Web Domain
Proceed with the default self-signed certificate
❗Note The default self-signed certificate will cause browsers to display security warnings and may block access unless manually allowed.
Preparing the Certificate
Follow the guide Preparing TLS Certificates to obtain the certificate files:
portsip.keyportsip.pem
Configuring the Certificate
In this guide, we assume the use of the domain uc.portsip.cc for the PBX web domain.
In the Web Domain field, enter uc.portsip.cc.
Open the portsip.pem file in a text editor (such as Windows Notepad), and copy the entire contents into the Certificate File field.
Similarly, open the portsip.key file, and copy its entire contents into the Private Key File field.
Step 3: Transport Protocol
Configure the SIP transport protocols by clicking Add.
Default transport ports are:
UDP: 5060
TCP: 5063
TLS: 5061
You may change these ports if required, provided the selected ports are not already in use by other services.
❗Important After adding or modifying transport protocols, update your firewall rules to allow traffic on the configured ports. IP phones and client applications will use these ports to connect to the PBX.
Step 4: Reboot to Apply SSL Certificate
If you uploaded a trusted SSL certificate (instead of using the default self-signed certificate), you must restart the PBX to apply the changes.
The following command must be executed only on the EC2 instance with the private IP address 172.31.16.133.
After the restart, you can now access the PBX Web Portal at: https://uc.portsip.cc:8887
Install PortSIP IM Service
With the PortSIP PBX High Availability deployment complete, you are now ready to install the PortSIP Instant Messaging (IM) Service.
Please follow the Scaling IM Server on AWS for High Availability guide to complete the installation and configuration.
Install PortSIP Data Flow Service
With the PortSIP PBX High Availability deployment complete, you are now ready to install the PortSIP Data Flow Service.
Please follow the Scaling Data Flow Server on AWS for High Availability guide to complete the installation and configuration.
Managing PBX HA
Once you have successfully configured PortSIP PBX High Availability (HA) using the steps above, you can manage and monitor the HA cluster using the commands provided in this section.
❗ Important All HA management commands must be executed only on the EC2 instance with the private IP address
172.31.16.133.
View PBX HA Status
To view the current status of the PBX HA cluster, run the following command:
A healthy HA cluster will produce output similar to the following.
This output indicates that:
The HA cluster is running normally
The EC2 instance
172.31.16.133is currently acting as the master nodeThe EC2 instances
172.31.16.134and172.31.16.135are operating as slave (standby) nodes
Check the Current Master Node
To identify which EC2 instance is currently acting as the master PBX node, run the following command:
The output will clearly indicate the EC2 instance that is currently hosting the active PBX services.
Restart PBX Service
To restart the PBX service within the HA cluster, use the following command:
A successful restart will produce output similar to the following:
This indicates that the PBX resource has been cleanly stopped and restarted under Pacemaker control.
Last updated