How to Use the Command 'asterisk' (with Examples)

Asterisk is a powerful and widely-used open-source software that serves as a telephone exchange and communication server. It enables users to connect calls, manage telephony, and implement various communication features via software-based server instances. The software is versatile enough to function as a traditional Private Branch Exchange (PBX) or integrate with Voice over IP (VoIP) services, providing functionalities like voicemail, call recording, and interactive voice response systems.

Use case 1: Reconnect to a Running Server with Verbosity

Code:

asterisk -r -vvv

Motivation for using the example: This command is crucial when the system administrator needs to diagnose or monitor call activities on an Asterisk server. By increasing verbosity, the administrator can gain more detailed insights into the operations and system events happening on the server, which is essential for troubleshooting and maintaining smooth operations.

Explanation:

• -r: This option reconnects to a running Asterisk server. It allows administrators to interact with the system without restarting it, ensuring continuous service availability.
• -vvv: The additional vs signify three levels of verbosity. Each v increases the amount of log information displayed, providing a granular view of the server’s activities and diagnostic messages.

Example Output:

Asterisk 18.0.0, Copyright (C) 1999 - 2021, Digium, Inc.
Created by Mark Spencer <markster@digium.com>
...

Verbosity was 3 and is now 3
...
Channel SIP/1000-00000002 was answered.
-- Executing [2000@internal:1] Answer("SIP/1000-00000002", "") in new stack
-- <SIP/1000-00000002> Playing 'vm-goodbye.gsm' (language 'en')

Use case 2: Reconnect to a Running Server and Execute a Single Command

Code:

asterisk -r -x "command"

Motivation for using the example: This capability is particularly useful for efficiently managing the server through automation scripts or when quick, one-off command execution is necessary without prolonged interaction with the server. It allows system administrators to check statuses or make changes in a quick and effective manner.

Explanation:

• -r: Again, this reconnects to the running Asterisk server, enabling user interaction.
• -x "command": This flag is used to execute a specific command within the server’s environment. The command is passed as a string and executed once, allowing for immediate execution and response retrieval.

Example Output: For a command like core show uptime, you might see:

System uptime: 5 days, 3 hours, 20 minutes, 45 seconds

Use case 3: Show Channel SIP Clients

Code:

asterisk -r -x "sip show peers"

Motivation for using the example: In environments where VoIP services are critical, knowing the list of connected clients can help in auditing, security checks, and network management. It provides visibility into who is connected and ensures that all expected or authorized peers are accounted for.

Explanation:

• -r and -x: These options are used as previously explained to connect to the server and execute a command.
• "sip show peers": This specific command lists all SIP (Session Initiation Protocol) peers, essentially showing connected phone devices, their IP addresses, status, and latency.

Example Output:

Name/username         Host            Dyn Nat ACL Port     Status
1001/1001             192.168.1.25    D   N      5060     OK (53 ms)
1002/1002             192.168.1.26    D   N      5060     OK (48 ms)

Use case 4: Show Active Calls and Channels

Code:

asterisk -r -x "core show channels"

Motivation for using the example: Understanding the number of active channels and calls in real-time is vital for monitoring server load and ensuring the quality of service during peak usage periods. This data helps in capacity planning and determining if the server is operating within its optimal parameters.

Explanation:

• -r and -x: Standard options for server interaction and command execution.
• "core show channels": This command provides details on currently active call channels, which helps in understanding the load and active call routing through the server.

Example Output:

Channel              Location           State   Application(Data)
SIP/1001-00000001    s@dialer            Up      Dial(SIP/trunk/123456...)
SIP/1002-00000002    s@internal          Up      AppDial((Outgoing Line))
2 active channels

Use case 5: Show Voicemail Mailboxes

Code:

asterisk -r -x "voicemail show users"

Motivation for using the example: This command is useful for administrators who need to manage voicemail accounts, especially in environments where voicemail is a key feature. It allows for monitoring active voicemail boxes and managing subscriber accounts.

Explanation:

• -r and -x: Used as previously specified to reconnect and execute a command.
• "voicemail show users": This command lists the current voicemail users configured on the Asterisk server, which can be used to verify account setups and monitor system usage.

Example Output:

Context    Mailbox    NewMsg
internal   1001       0
internal   1002       3

Use case 6: Terminate a Channel

Code:

asterisk -r -x "hangup request channel_ID"

Motivation for using the example: During troubleshooting or emergency situations where a problematic call needs to be terminated, this command becomes invaluable. It provides the ability to immediately disconnect a specific call channel, ensuring any issues such as network abuse or call loops can be resolved promptly.

Explanation:

• -r and -x: As before, these options connect to the server and execute a provided command.
• "hangup request channel_ID": This command disconnects a specified call channel, identified by its channel_ID. It’s particularly useful for terminating unexpected or unauthorized call activities.

Example Output:

Requesting Hangup on channel SIP/1001-00000001

Use case 7: Reload chan_SIP Configuration

Code:

asterisk -r -x "sip reload"

Motivation for using the example: Configuration changes for SIP peers often require that the changes be propagated without affecting current operations. This command allows for reloading the SIP protocol configurations without requiring a full server restart, thereby maintaining uptime and service availability.

Explanation:

• -r and -x: Standard options to interact with the Asterisk server and execute commands.
• "sip reload": This command reloads the SIP configuration files, ensuring that any changes made to the settings become active without disrupting ongoing services.

Example Output:

Reloading SIP
Found peer '1001'
Found peer '1002'

Conclusion

Through these examples, the versatility and power of the Asterisk command are clearly demonstrated, providing essential tools for telephony server setup, management, and problem-solving. Each command serves a specific purpose, ensuring that server administrators can efficiently handle various telephony tasks and support operations.