안녕하세요
FreePBX 관련해서 물리적 측면 보다 SW적 확인할 일이 있어서 자료를 찾아보고 테스트해 본 내용을 공유드립니다.
FreePBX분야 전문 개발자가 아니다 보니, 실수한 내용들이 있을 수 있습니다.
참고 정도로 봐주시고, 잘못된 부분은 댓글 주시면 수정하도록 하겠습니다.
FreePBX에 접근해서 신호를 제어하기 위해서 AMI(Asterisk Manager Interface)를 먼저 알고 접속해야 합니다. 그래서 첫 번째 내용으로 간단한 이론과 접속하는 방법을 정해보았습니다.
API 방법도 있지만, AMI가 좀 더 제어권한이 많아 선택해서 테스트했습니다.
이후 AMI로 해볼 수 있는 기능을 python으로 몇 가지 테스트하는 글을 올려 보겠습니다.
테스트한 환경은 Virtual Box, FreePBX 15.0.23입니다.
1. AMI (Asterisk Manager Interface) 란?
AMI는 Asterisk Manager Interface의 약자로, Asterisk PBX 시스템의 상태를 모니터링하고 제어할 수 있도록 외부에 제공하는 프로그래밍 인터페이스입니다.
쉽게 말해, Asterisk 내부에서 일어나는 일들을 외부 프로그램이 확인하고, 전화를 걸거나 끊는 등의 명령을 내릴 수 있게 해주는 통신 창구라고 생각하면 됩니다.
1.1 AMI 주요 기능 및 역할
(1) 상태 모니터링: 현재 활성화된 통화 채널, 등록된 SIP 장치 상태, 통화 대기열(Queue) 상태 등 실시간 정보를 얻을 수 있습니다.
(2) 제어: 외부 프로그램에서 명령을 보내 전화를 걸거나(Originate), 채널을 끊거나(Hangup), 특정 설정을 변경하는 등의 작업을 수행할 수 있습니다.
(3) 이벤트 알림: 전화 수신, 통화 종료, 장치 상태 변경 등 Asterisk 내부에서 발생하는 다양한 이벤트를 실시간으로 외부 프로그램에 알려줍니다.
(4) 통합: CRM, 콜센터 솔루션, 커스텀 대시보드 등 다른 시스템과 Asterisk를 연동하는 데 핵심적인 역할을 합니다.
1.2 AMI를 사용 이유
(1) 자동화: 반복적인 전화 작업이나 상태 확인을 자동화할 수 있습니다.
(2) 맞춤형 솔루션 개발: FreePBX/Asterisk의 기본 기능을 넘어선 특화된 전화 관련 애플리케이션 개발이 가능합니다. (예: 클릭 투 콜, 실시간 통계 대시보드)
(3) 시스템 통합: 기존에 사용하던 다른 업무 시스템과 전화 시스템을 연동하여 업무 효율을 높일 수 있습니다.
2. AMI 접속 방법
AMI에 접속하려면 먼저 FreePBX에서 AMI 사용자를 생성하고 설정을 활성화해야 합니다. 그런 다음, Telnet과 같은 간단한 도구나 프로그래밍 언어를 사용하여 접속할 수 있습니다.
2.1. FreePBX에서 AMI 사용자 설정하기
2.1.1 FreePBX Web에서 계정 생성하기
FreePBX 웹 관리자 접속: FreePBX 관리자 페이지에 로그인합니다.
Asterisk Manager Users 이동: 상단 메뉴에서 Settings -> Asterisk Manager Users로 이동합니다.
설정 메뉴와 기능은 FreePBX 버전에 따라 다를 수 있습니다.
새 사용자 추가: + Add Manager 버튼을 클릭합니다.
사용자 정보 입력:
Manager Name: AMI 접속 시 사용할 사용자 이름(ID)
Manager Secret: AMI 접속 시 사용할 비밀번호(PASSWORD) - 보안을 위해 복잡하게 설정하는 것이 좋습니다.
Deny & Permit: 보안을 위해 특정 IP 주소나 네트워크 대역에서만 접속을 허용하도록 설정합니다.
Deny: 0.0.0.0/0.0.0.0 (기본적으로 모든 IP 차단)
Permit: 192.168.0.10/255.255.255.255 (특정 IP 허용) 또는 192.168.0.0/255.255.255.0 (특정 네트워크 대역 허용) - AMI에 접속할 클라이언트 PC 또는 서버의 IP 주소를 입력해야 합니다.
Permissions: 이 사용자에게 부여할 권한을 설정합니다. 특정 작업만 허용하려면 필요한 권한(예: read=system,call,log, write=originate,command)을 선택하고, 모든 권한을 주려면 all을 체크합니다. (보안상 필요한 최소한의 권한만 부여하는 것이 좋습니다.)
저장 및 적용: 사용자 정보를 입력하고 Submit 버튼을 누른 후, 상단의 Apply Config 버튼을 눌러 변경 사항을 적용합니다.
위와 같이 설정이 완료되면, manager_addtional.conf 파일에 계정정보가 추가됩니다.
2.1.2 리눅스 셀(Shell)에서 설정파일로 계정 생성
Virtual Box(FreePBX)의 리눅스 셀(Shell) 상에서 AMI 접속 계정 정보를 추가하거나 SSH로 FreePBX 서버에 접속하여 해당 파일 내용을 수정할 수 있습니다.
# SSH로 FreePBX 서버 접속 후 vim 혹은 nano로 편집합니다.
sudo vim /etc/asterisk/manager_custom.conf
계정정보를 아래의 형식으로 입력합니다. (테스트를 위해서 간단하게 ID, PW, 권한을 입력했습니다.)
2.2 Telnet 또는 nc(netcat)로 접속 테스트
AMI 접속을 테스트하는 방법은 Telnet 클라이언트나 nc (netcat) 유틸리티를 사용할 수 있습니다.
(1) 접속에 필요한 정보
FreePBX 서버 IP 주소 (예: 192.168.219.110)
AMI 포트 (기본값: 5038)
생성한 AMI 사용자 ID(Username) (예: myuser)
생성한 AMI 비밀번호(Secret) (예: myuser)
(2) Telnet 프로그램 windows용 Putty 이용하여 접속 테스트
Putty에 프로그램에서 telnet으로 선택하고 FreePBX 서버주소와 포트를 입력하고 "Open"을 눌러 접속합니다.
참고, 리눅스에서 nc 사용해서 접속 가능합니다.
$ nc 192.168.219.110 5038
(3) 접속 성공 시:
Asterisk Call Manager/X.Y.Z 와 같은 환영 메시지가 표시됩니다. (X.Y.Z는 AMI 프로토콜 버전)
2.3 AMI 로그인과 명령어 실행
(1) 로그인 명령어 실행
버전 메시지를 확인한 후, 로그인 명령어를 직접 입력하고 Enter 키를 두 번 눌러 전송합니다.
(명령어 끝에는 항상 빈 줄이 필요하며, 대소문자 구분하지 않습니다.)
Action: Login
Username: myuser
Secret: myuser
(Enter 키 두 번 입력)
로그인 성공 시 Response: Success와 Message: Authentication accepted 메시지가 포함된 응답이 옵니다. (명령어 뭉치를 복사해서 붙여넣기로 해도 됩니다. 로그인할 처음에 입력하면 에러가 나올 수 있습니다. 에러가 나오면 다시 붙여넣기 해서 엔터를 누르면 로그인됩니다.)
Web에서 만든 계정으로 접속한 경우
manger_custom.conf에서 만든 계정으로 접속한 경우
(2) 현재 채널 정보 명령어
로그인 후 다른 명령어를 실행해 볼 수 있습니다. (테스트는 manger_custom.conf에서 만든 계정으로 진행합니다.)
현재 활성 채널 정보를 보려면 action:과 함께 coreshowchannels를 입력하면 됩니다.
Action: CoreShowChannels
(Enter 키 두 번 입력)
(3) 로그아웃 명령어
종료하려면 로그아웃 명령을 보냅니다.
Action: Logoff
(Enter 키 두 번 입력)
3. AMI 접속 시 발생할 수 있는 문제
(1) 연결 거부 (Connection refused):
- FreePBX 서버의 방화벽에서 5038 포트가 열려 있는지 확인합니다.
- Asterisk Manager 서비스가 실행 중인지 확인합니다 (systemctl status asterisk 또는 fwconsole restart).
- AMI 설정에서 permit IP 주소가 현재 접속하려는 PC의 IP 주소를 포함하는지 확인합니다.
(2) 인증 실패 (Authentication failed):
- AMI 사용자 이름과 비밀번호가 정확한지 확인합니다. (대소문자 구분)
- FreePBX GUI에서 설정을 변경한 후 Apply Config를 눌렀는지 확인합니다.
다음 글에서는 Python 코드를 사용해서 AMI에 접속해서 명령어를 실행하는 방법 확인해 보겠습니다.
감사합니다.
<참고사이트>
1. AMI (Asterisk Manager Interface) configuration
https://hotkey404.com/ami-asterisk-manager-interface-configuration/
2. PBX GUI - AMI Default Configuration in 16
3. Asterisk & FreePBX: How To Create AMI User?
https://fatiherikci.com/en/asterisk-freepbx-ami-user/
4. AMI Libraries and Frameworks
'IT > Unified Communications' 카테고리의 다른 글
| RS485 통신에 대해서 알아보기 (0) | 2025.05.10 |
|---|---|
| [FreePBX]Python으로 FreePBX AMI 프로그래밍 테스트 1 (연결, Ping, 종료 흐름) (0) | 2025.05.01 |
| FreePBX 설치 후 나타날 수 있는 증상들-1 (전화를 걸면 거절, Cannot Connect To Asterisk) (4) | 2024.12.21 |
| FreePBX에 모듈(Module) 추가하는 방법 (Asterisk) (2) | 2024.12.18 |
| TinkerBoard 2S에 Asterisk 설치(소스컴파일, 패키지) 및 테스트해 보기 (설치 실패) (1) | 2024.11.23 |