Asterisk - The Open Source Telephony Project  21.4.1
func_shell.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006-2012, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16 
17 /*! \file
18  *
19  * SHELL function to return the output generated by a command issued to the system shell.
20  *
21  * \note Inspiration and Guidance from Russell! Thank You!
22  *
23  * \author Brandon Kruse <bkruse@digium.com>
24  *
25  * \ingroup functions
26  */
27 
28 /*** MODULEINFO
29  <support_level>core</support_level>
30  ***/
31 
32 #include "asterisk.h"
33 
34 #include "asterisk/module.h"
35 #include "asterisk/channel.h"
36 #include "asterisk/pbx.h"
37 #include "asterisk/utils.h"
38 #include "asterisk/app.h"
39 
40 static int shell_helper(struct ast_channel *chan, const char *cmd, char *data,
41  char *buf, size_t len)
42 {
43  int res = 0;
44 
45  if (ast_strlen_zero(data)) {
46  ast_log(LOG_WARNING, "Missing Argument! Example: Set(foo=${SHELL(echo \"bar\")})\n");
47  return -1;
48  }
49 
50  if (chan) {
52  }
53 
54  if (len >= 1) {
55  FILE *ptr;
56  char plbuff[4096];
57 
58  ptr = popen(data, "r");
59  if (ptr) {
60  while (fgets(plbuff, sizeof(plbuff), ptr)) {
61  strncat(buf, plbuff, len - strlen(buf) - 1);
62  }
63  pclose(ptr);
64  } else {
65  ast_log(LOG_WARNING, "Failed to execute shell command '%s'\n", data);
66  res = -1;
67  }
68  }
69 
70  if (chan) {
72  }
73 
74  return res;
75 }
76 
77 /*** DOCUMENTATION
78  <function name="SHELL" language="en_US">
79  <synopsis>
80  Executes a command using the system shell and captures its output.
81  </synopsis>
82  <syntax>
83  <parameter name="command" required="true">
84  <para>The command that the shell should execute.</para>
85  <warning><para>Do not use untrusted strings such as <variable>CALLERID(num)</variable>
86  or <variable>CALLERID(name)</variable> as part of the command parameters. You
87  risk a command injection attack executing arbitrary commands if the untrusted
88  strings aren't filtered to remove dangerous characters. See function
89  <variable>FILTER()</variable>.</para></warning>
90  </parameter>
91  </syntax>
92  <description>
93  <para>Collects the output generated by a command executed by the system shell</para>
94  <example title="Shell example">
95  exten => s,1,Set(foo=${SHELL(echo bar)})
96  </example>
97  <note>
98  <para>The command supplied to this function will be executed by the
99  system's shell, typically specified in the SHELL environment variable. There
100  are many different system shells available with somewhat different behaviors,
101  so the output generated by this function may vary between platforms.</para>
102 
103  <para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
104  is set to <literal>no</literal>, this function can only be executed from the
105  dialplan, and not directly from external protocols.</para>
106  </note>
107  </description>
108 
109  </function>
110  ***/
111 static struct ast_custom_function shell_function = {
112  .name = "SHELL",
113  .read = shell_helper,
114 };
115 
116 static int unload_module(void)
117 {
118  return ast_custom_function_unregister(&shell_function);
119 }
120 
121 static int load_module(void)
122 {
123  return ast_custom_function_register_escalating(&shell_function, AST_CFE_READ);
124 }
125 
126 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Collects the output generated by a command executed by the system shell");
const char * name
Definition: pbx.h:119
Main Channel structure associated with a channel.
Asterisk main include file. File version handling, generic pbx functions.
int ast_autoservice_start(struct ast_channel *chan)
Automatically service a channel for us...
Definition: autoservice.c:200
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Utility functions.
#define ast_custom_function_register_escalating(acf, escalation)
Register a custom function which requires escalated privileges.
Definition: pbx.h:1567
General Asterisk PBX channel definitions.
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
Core PBX routines and definitions.
int ast_autoservice_stop(struct ast_channel *chan)
Stop servicing a channel for us...
Definition: autoservice.c:266
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
Asterisk module definitions.
Application convenience functions, designed to give consistent look and feel to Asterisk apps...