Description of MikoPBX and the sections you can find in the documentation. Introduction to the documentation.
Foreword
Welcome to the MikoPBX documentation resource! Here you can find step-by-step instructions related to interacting with the MikoPBX PBX system. For your convenience, the documentation is organized into sections - just like in the web interface, making it very easy to navigate.
Thank you for choosing MikoPBX! ❤️
What is MikoPBX?
MikoPBX is a free telephony server with its own operating system and a simple, user-friendly web interface. It works with virtually any telephony technology in the world.
MikoPBX Interface
MikoPBX is a fully modular interface for Asterisk, written in PHP and JavaScript. This means that you can implement absolutely any additional Asterisk telephony functionality within MikoPBX. Moreover, if you develop a useful module, you can place it in the public repository and make it available to all MikoPBX users. Additionally, MikoPBX has very low hardware requirements:
Simultaneous Calls
Minimally Recommended Configuration
To get started, you should install MikoPBX using any method convenient for you. Below are installation options. By clicking on their names, you can access detailed articles:
Installation .
Installation .
Installation .
Installation in a
After installation, you can begin exploring your PBX system. The "User Guide" documentation will help you with this, providing detailed information about specific sections:
.
.
.
.
For additional help with getting started quickly, you can refer to .
If you have familiarized yourself with the basic setup and operation of MikoPBX, you can expand its functionality using modules.
Modules allow you to add extra features to your system. You can learn more about them step by step:
– here you'll find a detailed description of the registration process and its specifics.
– this section provides a detailed explanation of how to install and manage modules.
– in this section, you'll find detailed descriptions of each module, as well as steps for configuring and using them.
In this section, you can find answers to your questions and solutions that will help you expand the functionality of basic features. This section, like the main documentation, is divided into categories for easy navigation.
If you have a question that isn't covered here, you can seek assistance in the , where MikoPBX users help each other resolve issues and needs related to the PBX system.
Discription of system requirements for the MikoPBX system
Network Channel Requirement
An example of calculating the required channel bandwidth for different codecs for 30 simultaneous calls. PBX supports the most popular codecs:
G.711 - 4.67 Mbps
GSM - 1.68 Mbps
G.722 - 4.67 Mbps
G.729 - 1.38 Mbps
800 Mb hard disk for the main system
A 50+ Gb hard drive for recording conversations
1 (2 cores) x86-64 processor
2 GB of RAM
Network Adapter
The calculation is approximate, when using the same codec on all devices connected to the PBX. Read more here.
Minimum system requirements
We recommend using two hard drives for PBX deployment.
A PC with such parameters, in our tests, holds 38 simultaneous incoming calls under the conditions:
10 agents are connected to the queue (all online)
Every second a new call comes in
Music (MOH) is played to the client while waiting
Modules on the PBX is not installed
Approximately, 1 hour of conversation takes up 14MB of disk space. The recommended size for the disk storing call recordings is at least 50 gigabytes.
Getting to know MikoPBX
Description of the first login to the MikoPBX web-interface
First login to the MikoPBX system
Go to the MikoPBX installation console, remember the IP address that your PBX received.
MikoPBX IP address for connecting to the WEB interface
Enter the received MikoPBX IP address in the web browser. The authorization page will be displayed. Log in using the default credentials:
Use the following default credentials for the first login to the MikoPBX web interface:
Username: admin
Password: admin
Authorization page in the web interface
After successful authorization, MikoPBX will automatically open the settings for changing the password:
First authorization in the MikoPBX WEB interface
For more information about the General Settings, see the section.
After changing the password, the system will be fully operational. It is recommended to immediately configure the firewall rules. You can read about how to do this by following the link.
This guide provides detailed steps to get started with MikoPBX and helps you quickly configure the system.
Follow the step-by-step instructions in the order presented for a quick and successful system setup.
Installing MikoPBX
MikoPBX is a full-fledged operating system for your hardware; it is not a standalone application. It is provided as an image file (*.iso, *.img, *.raw).
Follow the link for your preferred installation method and proceed according to the provided instructions.
After installation, you need to access the MikoPBX web interface for further system configuration. To do this, find the PBX's IP address in the MikoPBX console:
In this example, the IP address is 192.168.0.203. To access the web interface, enter this IP address into your browser's address bar:
After the first login, the system will prompt you to change your password.
For stable PBX operation, you need to configure the network through the Network and Firewall → Network Interface section. Detailed instructions for these settings can be found .
In MikoPBX, all local subnets can be defined in the Network and Firewall → Firewall section. The firewall is intended to restrict access to the PBX based on traffic type and subnets. Follow the setup instructions .
Fail2Ban blocks IP addresses exhibiting unusual activity; it can reduce the rate of failed authentication attempts and helps protect your PBX from hacking. Instructions to help with the setup can be found .
After completing the initial PBX setup, you can proceed to create accounts for your employees. This will assist you.
After adding employees, you need to connect providers to your PBX. Instructions for this section can be found . Instructions with examples of configuring real providers can be found .
At this stage, you need to set routing rules for incoming and outgoing calls: how calls passing through a specific provider will be handled:
To create routing rules, you may also need the following features:
The Marketplace allows you to extend the system's standard functionality using modules:
You can read more about Modules in MikoPBX in .
Information on registering in the MikoPBX Marketplace can be found .
First Login to the Web Interface
If the logs do not provide a username and password, use the default credentials:
Username: admin
Password: admin
Settings Within the Web Interface:
Network and Firewall Settings
Configuring Protection Against Hacking (Fail2Ban)
Adding and Configuring Employee Accounts
Connecting Providers
Setting Up Incoming and Outgoing Routing
Marketplace and Modules
This completes the basic setup of MikoPBX! For a deeper exploration of MikoPBX's capabilities, we recommend referring to the comprehensive documentation.
How to protect MikoPBX from hacking and unauthorized access
IP PBX systems are increasingly being targeted by attackers. Criminals gain access to your telephony and make calls at your expense - to premium numbers and international destinations. This can result in losses of tens or hundreds of thousands of dollars within just a few hours.
Beyond direct financial losses, a compromised PBX can be used by fraudsters to make calls on behalf of your organization - for example, calling citizens while impersonating banks or government agencies. Victims see your company's phone number, causing reputational damage and potential investigations by law enforcement.
Go through every item in this guide - even if you have already configured the system, something may have been missed.
⚠️ Critical vulnerability in version 2024.1.114!
A vulnerability has been discovered in the external panel module: if the module is exposed to the internet or the Firewall is misconfigured, an attacker can obtain all SIP credentials and make calls on behalf of your company.
You must perform the following steps:
Security Patch for Version 2024.1.114
If you are running version 2024.1.114, install the patch with a single command:
curl -L 'https://files.miko.ru/s/DPZcM2vywc2BTOZ/download' | sh
If you are using an older version — upgrade to the latest release. Steps 3 and 4 from the list above must be completed regardless of your version.
The firewall is your first line of defense. It restricts who can connect to your PBX.
Go to Network and Firewall → Network Firewall, make sure the toggle is enabled, and create rules that allow access only from the required subnets.
Addresses to add to your rules:
Your office subnet
VPN server addresses
Your telephony provider's IP addresses (check with your provider)
Static IP addresses of remote employees
The PBX admin panel is effectively the "master key" to the entire system. If it is accessible from the internet without restrictions, an attacker can gain full control over your telephony.
In the firewall rules, allow WEB and CTI access only for your office subnet or VPN. For all other rules, uncheck the WEB and CTI boxes. If you need remote access — use a VPN.
A weak password is the most common cause of a breach. Attackers try thousands of combinations per second, and passwords like 1234, admin, or password are cracked instantly.
Password requirements for SIP accounts and the web interface:
Minimum 12 characters
UPPER and lowercase letters
Numbers and special characters (!@#$%^&*)
What to check:
Open each employee's profile under Telephony → Extensions and verify that the SIP password is sufficiently complex.
Check the web interface password under System → General Settings → WEB interface password.
By default, the employee's extension number (e.g., 204) is used for SIP authentication. Attackers know this and specifically target standard extension numbers.
Auth Username is the username that a phone or softphone sends when registering with the PBX. It differs from the internal extension number and is used solely for authenticating the connection.
How to configure the Auth Username prefix in MikoPBX:
Go to System → General Settings → SIP and fill in the Auth Username prefix for authorization field. For example, with the prefix MIKO, extension 204 will authenticate as 204MIKO.
After changing the Auth Username, you must update the settings on every phone or softphone. The setting name varies by manufacturer:
Manufacturer
Setting Name
This setting is typically found under the Account or SIP Account section in the phone's web interface.
Fail2Ban automatically blocks IP addresses that exhibit suspicious connection attempts.
Go to Network and Firewall → Intrusion Protection and review the configured protection level:
Weak — 20 attempts in 10 min, ban for 10 min. For initial setup and trusted networks.
Normal — 10 attempts in 1 hour, ban for 1 day. Recommended for most deployments.
Strong — 5 attempts in 6 hours, ban for 7 days. For internet-facing servers.
Warning: Make sure your office addresses are added to the whitelist to avoid accidentally locking yourself out.
Fail2Ban does not replace strong passwords - even with Fail2Ban enabled, a weak password can still be brute-forced.
Docker deployment: in bridge mode the built-in firewall and fail2ban do not protect the web interface. Set up an or switch the container to network_mode: host.
If your PBX is directly accessible from the internet, it becomes a target for automated scanners that continuously search for vulnerable systems.
Place the PBX behind a NAT router.
Use VPN connections for remote employees.
If a public IP is unavoidable — be sure to configure the Firewall and Fail2Ban.
Under Network and Firewall → Network interfaces
Even with strong technical security, it is worth adding a financial safety net. If a breach does occur, these measures will limit potential losses.
Contact your telephony provider and request:
A daily spending limit on outbound calls
A block on service when the balance is negative
Blocking of international and premium-rate calls if you do not use them
Top up your balance in small amounts as needed.
Set up spending alerts with your provider if that option is available.
If you discover that your PBX has been compromised, follow these steps:
Step 1 — Isolate the PBX Immediately
Block all external access via the firewall. Change all passwords — SIP accounts, web interface, SSH.
Step 2 — Save Logs and Call Recordings
Save call recording files and system logs separately — they may be needed as evidence. They can be overwritten over time.
Step 3 — Notify Your Telephony Provider
Contact your telephony provider and report the incident. The provider may be able to block further calls and officially document the breach.
Step 4 — Report the Incident to the Relevant Authorities
File a report with your national cybercrime authority or law enforcement agency. Briefly describe what happened, state that calls were made without your knowledge, and indicate that you are prepared to provide logs and call recordings as evidence.
Go through this list and confirm that every item has been completed:
— configuring access rules.
— network configuration, NAT, DNS.
No dictionary words, names, or dates of birth
Snom
Authentication Username
Linphone
Auth userid
Zoiper
Authentication user / Auth. Username
MicroSIP
Login
Cisco (SPA)
Auth ID
Paranoid — 3 attempts in 24 hours, ban for 30 days. For servers under active attack.
, correctly specify the network topology and external address.
— manual routing configuration.
Extensions — managing accounts and SIP passwords.
Upgrade to version 2026.1.223 or newer.
Install the security patch (see below).
Close WEB, CTI, and SIP access to the PBX from external networks.
Update all passwords.
Yealink
Register Name / Authentication User
Grandstream
Authenticate ID
Fanvil
Authentication User
Mandatory Security Measures
Enable the Firewall
Note: For remote employees with dynamic IPs, we recommend purchasing a static IP address from their ISP (typically very low cost per month). An alternative is VPN: all remote employees connect through a VPN server, and only that server's address is added to the Firewall.
