Asterisk cmd System

This document is out of date! Please visit the Asterisk wiki for up to date information — App_System Documentation. For historical reference, the original information is below.

System() For Asterisk >=1.2

Synopsis

Execute a system (Linux shell) command

Description

System(command) – System command alone
System(command arg1 arg2 etc) – Pass in some arguments
System(command|args) – Use the standard asterisk syntax to pass in arguments

Technical Info

Executes a command by using system().
System() passes the string unaltered to system(3). Running “man 3 system” will show exactly what system(3) does:

system() executes a command specified in string by calling
/bin/sh -c string, and returns after the command has been completed.

Therefore System(command arg1 arg2 etc) can be used to pass along arguments.

Return codes

System(command): Executes a command by using system(). If the command fails, the console should report a fallthrough.
If you need to return a specific value (string) to the dialplan then use either AGI or Asterisk func shell as introduced in Asterisk 1.6.0.

Result of execution is returned in the SYSTEMSTATUS channel variable:

FAILURE Could not execute the specified command
SUCCESS Specified command successfully executed
APPERROR Triggered for example when you try to delete a file but the file was not there.
NOTE – not documented, but can also return APPERROR
NOTE – I don’t seem to be able to create a situation when FAILURE will be returned.

As far as I can understand it will return APPERROR when the command exits with a non-zero return-value.

Old behaviour:

If the command itself executes but is in error, and if there exists a priority n + 101, where ‘n’ is the priority of the current instance, then the channel will be setup to continue at that priority level. Note that this jump functionality has been deprecated and will only occur if the global priority jumping option is enabled in extensions.conf (priorityjumping=yes).

app_backticks (3rd party addition)

Example 1

exten => s,1,system(echo “${DATETIME} – ${CALLERID} – ${CHANNEL}” >> /var/log/asterisk/calls)

Example 2

; dial 700 = Restart Asterisk
 exten => 700,1,Playback(posix-restarting) ; "Restarting asterisk"
 exten => 700,2,Wait(1)
 exten => 700,3,System(/usr/sbin/asterisk -rx reload)
 exten => 700,4,Hangup

Example 3

; Extension 200 Mini Call ID WinPopup Example
 exten => 200,1,NoOp(${CALLERID} ${DATETIME})
 exten => 200,2,System(/bin/echo -e "'Incoming Call From: ${CALLERID} \\r Received: ${DATETIME}'"|/usr/bin/smbclient -M target_netbiosname)
 exten => 200,3,Dial,sip/sipuser|30|t        
 exten => 200,4,Congestion

Example 4

 ; Dump call info to a serial receipt printer on ttyS1
 exten => 200,1,NoOp(${CALLERID} ${DATETIME})
 exten => 200,2,System(/bin/echo "'${CALLERID} ${DATETIME}'" > /dev/ttyS1)
 exten => 200,3,Dial,sip/sipuser|30|t        
 exten => 200,4,Congestion

Security

My associate received a call from PG&E and realized the horror of System()

Problem

Running System() has access to any program the user running asterisk has access to
CALLERID can be set by a remote user

Example

exten => 200,1,Set(CALLERID(NAME)=PG&/bin/echo BADIDEA > /ROOTED.txt)
exten => 200,2,System(/bin/echo -e “‘Incoming Call From: ${CALLERID} \\r Received: ${DATETIME}'”|/usr/bin/smbclient -M target_netbiosname)

Measure 1

By using perl I was able to prevent the first example but I’m sure the possibility is still there:

exten => 200,1,Set(CALLERID(NAME)=PG&/bin/echo BADIDEA > /ROOTED.txt)
exten => 200,2,System(/bin/perl -e ‘print Incoming Call From:” . “${CALLERIDNAME}” | /usr/bin/smbclient -M target_netbiosname)

Measure 2

Fine tune this to your liking:

[macro-smb-cid]
exten => s,1,NoOp
exten => s,2,Set(regx=”([a-zA-Z0-9]+)”)
exten => s,3,Set(CCIDNAME=$[“${CALLERIDNAME}”: ${regx}])
exten => s,4,Set(regx=”([0-9]+)”)
exten => s,5,Set(CCIDNUM=$[“${CALLERIDNUM}”: ${regx}])
exten => s,6,TrySystem(/usr/bin/perl -e \’print “${DATETIME} ” . ” ${CCIDNAME} ” . ” \<${CCIDNUM}\>” \’ | /usr/bin/smbclient -M target_netbiosname)

Update!! Asterisk-1.4 returns 0 (as it should) when your regex matches. Instead use the function FILTER.
This example is experimental…
[macro-smb-cid]
exten => s,1,NoOp
exten => s,2,Set(FLTNA=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz)
exten => s,3,Set(CIDNA=${FILTER(${FLTNA},${CALLERID(NAME)})})
exten => s,4,Set(FLTNU=(0123456789)
exten => s,5,Set(CIDNU=${FILTER(${FLTNU},${CALLERID(num)})})
exten => s,6,TrySystem(/usr/bin/perl -e \’print “${DATETIME} ” . ” ${CCIDNAME} ” . ” \<${CCIDNUM}\>” \’ | /usr/bin/smbclient -M target_netbiosname)

I’d like to hear from you if you know another way… [email protected]
what’s wrong with using System(su userWithNoRights -c “some command”) ?

See also

• Asterisk cmd TrySystem: Unlike System() returns 0 on any situation
• Asterisk func shell: Function to return a value from a Shell script (introduced in Asterisk 1.6.0)
• Asterisk cmd ReadFile – Read contents of a file into a dialplan variable
• Backticks: Application to return a value from a Shell script
• Asterisk cmd ExecIf: Conditionally execute a dialplan application
• AGI: Asterisk Gateway Interface
• Call notification: Example for generating pop-up messages

Asterisk | Applications | Functions | Variables | Expressions | Asterisk FAQ