Documentation Updates.
[asterisk/asterisk.git] / doc / asterisk.sgml
1 <refentry>
2 <refentryinfo>
3         <date>2011-02-08</date>
4 </refentryinfo>
5 <refmeta>
6         <refentrytitle>
7                 <application>asterisk</application>
8         </refentrytitle>
9         <manvolnum>8</manvolnum>
10         <refmiscinfo>asterisk Trunk</refmiscinfo>
11 </refmeta>
12 <refnamediv>
13         <refname>
14                 <application>asterisk</application>
15         </refname>
16         <refpurpose>
17         All-purpose telephony server.
18         </refpurpose>
19 </refnamediv>
20 <refsynopsisdiv>
21         <cmdsynopsis>
22         <command>asterisk</command>
23 <arg><option>-BcdfFghiImnpqRtTvVW</option></arg>
24 <arg><option>-C </option><replaceable class="parameter">file</replaceable></arg>
25 <arg><option>-e </option><replaceable class="parameter">memory</replaceable></arg>
26 <arg><option>-G </option><replaceable class="parameter">group</replaceable></arg>
27 <arg><option>-L </option><replaceable class="parameter">loadaverage</replaceable></arg>
28 <arg><option>-M </option><replaceable class="parameter">value</replaceable></arg>
29 <arg><option>-U </option><replaceable class="parameter">user</replaceable></arg>
30 <arg><option>-s </option><replaceable class="parameter">socket-file</replaceable></arg>
31 <arg><option>-x </option><replaceable class="parameter">command</replaceable></arg>
32         </cmdsynopsis>
33         <cmdsynopsis>
34
35         <command>asterisk -r</command>
36         <arg><option>-v</option></arg>
37 <arg><option>-x </option><replaceable class="parameter">command</replaceable></arg>
38         </cmdsynopsis>
39 </refsynopsisdiv>
40 <refsect1>
41         <refsect1info>
42                 <date>2011-02-08</date>
43         </refsect1info>
44         <title>DESCRIPTION</title>
45         <para>
46         <command>asterisk</command> is a full-featured telephony server which
47         provides Private Branch eXchange (PBX), Interactive Voice Response (IVR),
48         Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, 
49         Conferencing, and a plethora of other telephony applications to a broad
50         range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny,
51         H.323, Unistim) devices (both endpoints and proxies), as well as traditional TDM
52         hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart,
53         ISDN BRI and many more.
54         </para>
55         <para>
56         At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration
57         file and locates the rest of the configuration files from the configuration
58         in that file. The -C option specifies an alternate main configuration file.
59         Virtually all aspects of the operation of asterisk's configuration files
60         can be found in the sample configuration files.  The format for those files
61         is generally beyond the scope of this man page.
62         </para>
63         <para>
64         When running with <command>-c</command>, <command>-r</command> or <command>-R</command>
65         options, Asterisk supplies a powerful command line, including command
66         completion, which may be used to monitors its status, perform a variety
67         of administrative actions and even explore the applications that are
68         currently loaded into the system.
69         </para>
70         <para>
71         Asterisk is a trademark of Digium, Inc.
72         </para>
73 </refsect1>
74 <refsect1>
75         <title>OPTIONS</title>
76         <variablelist>
77         <varlistentry>
78                 <term>-B</term>
79                 <listitem>
80                         <para>
81                         Force the background of the terminal to be black, in order for
82                         terminal colors to show up properly.
83                         </para>
84                 </listitem>
85         </varlistentry>
86         <varlistentry>
87                 <term>-C <replaceable class="parameter">file</replaceable></term>
88                 <listitem>
89                         <para>
90                         Use <filename>file</filename> as master configuration file
91                         instead of the default, /etc/asterisk/asterisk.conf
92                         </para>
93                 </listitem>
94         </varlistentry>
95         <varlistentry>
96                 <term>-c</term>
97                 <listitem>
98                         <para>
99                         Provide a control console on the calling terminal.
100                         Specifying this option implies <command>-f</command> and will cause
101                         asterisk to no longer fork or detach from the controlling terminal.
102                         </para>
103                 </listitem>
104         </varlistentry>
105         <varlistentry>
106                 <term>-d</term>
107                 <listitem>
108                         <para>
109                         Enable extra debugging statements.
110                         </para>
111                         <para>
112                         Note: This always sets the debug level in the asterisk process,
113                         even if it is running in the background. This may affect the size
114                         of your log files, if the debug level is specified in logger.conf.
115                         </para>
116                 </listitem>
117         </varlistentry>
118         <varlistentry>
119                 <term>-e <replaceable class="parameter">memory</replaceable></term>
120                 <listitem>
121                         <para>
122                         Limit the generation of new channels when the amount of free memory has decreased to under <replaceable>memory</replaceable> megabytes.
123                         </para>
124                 </listitem>
125         </varlistentry>
126         <varlistentry>
127                 <term>-f</term>
128                 <listitem>
129                         <para>
130                         Do not fork or detach from controlling terminal.  Overrides any preceding specification of <command>-F</command> on the command line.
131                         </para>
132                 </listitem>
133         </varlistentry>
134         <varlistentry>
135                 <term>-F</term>
136                 <listitem>
137                         <para>
138                         Always fork and detach from controlling terminal.  Overrides any preceding specification of <command>-f</command> on the command line.
139                         </para>
140                 </listitem>
141         </varlistentry>
142         <varlistentry>
143                 <term>-g</term>
144                 <listitem>
145                         <para>
146                         Remove resource limit on core size, thus forcing Asterisk to dump
147                         core in the unlikely event of a segmentation fault or abort signal.
148                         <command>NOTE:</command> in some cases this may be incompatible
149                         with the <command>-U</command> or <command>-G</command> flags.
150                         </para>
151                 </listitem>
152         </varlistentry>
153         <varlistentry>
154                 <term>-G <replaceable class="parameter">group</replaceable></term>
155                 <listitem>
156                         <para>
157                         Run as group <replaceable>group</replaceable> instead of the
158                         calling group.  <command>NOTE:</command> this requires substantial work
159                         to be sure that Asterisk's environment has permission to write
160                         the files required for its operation, including logs, its comm
161                         socket, the asterisk database, etc.
162                         </para>
163                 </listitem>
164         </varlistentry>
165         <varlistentry>
166                 <term>-h</term>
167                 <listitem>
168                         <para>
169                         Provide brief summary of command line arguments and terminate.
170                         </para>
171                 </listitem>
172         </varlistentry>
173         <varlistentry>
174                 <term>-i</term>
175                 <listitem>
176                         <para>
177                         Prompt user to intialize any encrypted private keys for IAX2
178                         secure authentication during startup.
179                         </para>
180                 </listitem>
181         </varlistentry>
182         <varlistentry>
183                 <term>-I</term>
184                 <listitem>
185                         <para>
186                         Enable internal timing if DAHDI timing is available.
187                         The default behaviour is that outbound packets are phase locked
188                         to inbound packets. Enabling this switch causes them to be
189                         locked to the internal DAHDI timer instead.
190                         </para>
191                 </listitem>
192         </varlistentry>
193         <varlistentry>
194                 <term>-L <replaceable class="parameter">loadaverage</replaceable></term>
195                 <listitem>
196                         <para>
197                         Limits the maximum load average before rejecting new calls.  This can
198                         be useful to prevent a system from being brought down by terminating
199                         too many simultaneous calls.
200                         </para>
201                 </listitem>
202         </varlistentry>
203         <varlistentry>
204                 <term>-m</term>
205                 <listitem>
206                         <para>
207                         Temporarily mutes output to the console and logs.  To return to normal,
208                         use <command>logger mute</command>.
209                         </para>
210                 </listitem>
211         </varlistentry>
212         <varlistentry>
213                 <term>-M <replaceable class="parameter">value</replaceable></term>
214                 <listitem>
215                         <para>
216                         Limits the maximum number of calls to the specified value.  This can
217                         be useful to prevent a system from being brought down by terminating
218                         too many simultaneous calls.
219                         </para>
220                 </listitem>
221         </varlistentry>
222         <varlistentry>
223                 <term>-n</term>
224                 <listitem>
225                         <para>
226                         Disable ANSI colors even on terminals capable of displaying them.
227                         </para>
228                 </listitem>
229         </varlistentry>
230         <varlistentry>
231                 <term>-p</term>
232                 <listitem>
233                         <para>
234                         If supported by the operating system (and executing as root),
235                         attempt to run with realtime priority for increased performance and
236                         responsiveness within the Asterisk process, at the expense of other
237                         programs running on the same machine.
238                         </para>
239                         <para>
240                         Note: <command>astcanary</command> will run concurrently with
241                         <command>asterisk</command>. If <command>astcanary</command> stops
242                         running or is killed, <command>asterisk</command> will slow down to
243                         normal process priority, to avoid locking up the machine.
244                         </para>
245                 </listitem>
246         </varlistentry>
247         <varlistentry>
248                 <term>-q</term>
249                 <listitem>
250                         <para>
251                         Reduce default console output when running in conjunction with
252                         console mode (<command>-c</command>).
253                         </para>
254                 </listitem>
255         </varlistentry>
256         <varlistentry>
257                 <term>-r</term>
258                 <listitem>
259                         <para>
260                         Instead of running a new Asterisk process, attempt to connect
261                         to a running Asterisk process and provide a console interface
262                         for controlling it.
263                         </para>
264                 </listitem>
265         </varlistentry>
266         <varlistentry>
267                 <term>-R</term>
268                 <listitem>
269                         <para>
270                         Much like <command>-r</command>.  Instead of running a new Asterisk process, attempt to connect
271                         to a running Asterisk process and provide a console interface
272                         for controlling it. Additionally, if connection to the Asterisk 
273                         process is lost, attempt to reconnect for as long as 30 seconds.
274                         </para>
275                 </listitem>
276         </varlistentry>
277         <varlistentry>
278                 <term>-s <replaceable class="parameter">socket file name</replaceable></term>
279                 <listitem>
280                         <para>
281                         In combination with <command>-r</command>, connect directly to a specified
282                         Asterisk server socket.
283                         </para>
284                 </listitem>
285         </varlistentry>
286         <varlistentry>
287                 <term>-t</term>
288                 <listitem>
289                         <para>
290                         When recording files, write them first into a temporary holding directory, 
291                         then move them into the final location when done.
292                         </para>
293                 </listitem>
294         </varlistentry>
295         <varlistentry>
296                 <term>-T</term>
297                 <listitem>
298                         <para>
299                         Add timestamp to all non-command related output going to the console
300                         when running with verbose and/or logging to the console.
301                         </para>
302                 </listitem>
303         </varlistentry>
304         <varlistentry>
305                 <term>-U <replaceable class="parameter">user</replaceable></term>
306                 <listitem>
307                         <para>
308                         Run as user <replaceable>user</replaceable> instead of the
309                         calling user.  <command>NOTE:</command> this requires substantial work
310                         to be sure that Asterisk's environment has permission to write
311                         the files required for its operation, including logs, its comm
312                         socket, the asterisk database, etc.
313                         </para>
314                 </listitem>
315         </varlistentry>
316         <varlistentry>
317                 <term>-v</term>
318                 <listitem>
319                         <para>
320                         Increase the level of verboseness on the console.  The more times
321                         <command>-v</command> is specified, the more verbose the output is.
322                         Specifying this option implies <command>-f</command> and will cause
323                         asterisk to no longer fork or detach from the controlling terminal.
324                         This option may also be used in conjunction with <command>-r</command>
325                         and <command>-R</command>.
326                         </para>
327                         <para>
328                         Note: This always sets the verbose level in the asterisk process,
329                         even if it is running in the background. This will affect the size
330                         of your log files.
331                         </para>
332                 </listitem>
333         </varlistentry>
334         <varlistentry>
335                 <term>-V</term>
336                 <listitem>
337                         <para>
338                         Display version information and exit immediately.
339                         </para>
340                 </listitem>
341         </varlistentry>
342         <varlistentry>
343                 <term>-W</term>
344                 <listitem>
345                         <para>
346                         Display colored terminal text as if the background were white
347                         or otherwise light in color.  Normally, terminal text is displayed
348                         as if the background were black or otherwise dark in color.
349                         </para>
350                 </listitem>
351         </varlistentry>
352         <varlistentry>
353                 <term>-x <replaceable class="parameter">command</replaceable></term>
354                 <listitem>
355                         <para>
356                         Connect to a running Asterisk process and execute a command on
357                         a command line, passing any output through to standard out and
358                         then terminating when the command execution completes.  Implies
359                         <command>-r</command> when <command>-R</command> is not explicitly
360                         supplied.
361                         </para>
362                 </listitem>
363         </varlistentry>
364         <varlistentry>
365                 <term>-X</term>
366                 <listitem>
367                         <para>
368                         Enables executing of includes via <command>#exec</command> directive.
369                         This can be useful if You want to do <command>#exec</command> inside
370                         <filename>asterisk.conf</filename>
371                         </para>
372                 </listitem>
373         </varlistentry>
374         </variablelist>
375 </refsect1>
376 <refsect1>
377         <title>EXAMPLES</title>
378         <para>
379         <command>asterisk</command> - Begin Asterisk as a daemon
380         </para>
381         <para>
382         <command>asterisk -vvvgc</command> - Run on controlling terminal
383         </para>
384         <para>
385         <command>asterisk -rx "core show channels"</command> - Display channels on running server
386         </para>
387 </refsect1>
388 <refsect1>
389         <title>BUGS</title>
390         <para>
391         Bug reports and feature requests may be filed at https://issues.asterisk.org
392         </para>
393 </refsect1>
394 <refsect1>
395         <title>SEE ALSO</title>
396         <para>
397         *CLI&gt; <command>help</command> - Help on Asterisk CLI
398         </para>
399         <para>
400         *CLI&gt; <command>core show applications</command> - Show loaded dialplan applications
401         </para>
402         <para>
403         *CLI&gt; <command>core show functions</command> - Show loaded dialplan functions
404         </para>
405         <para>
406         *CLI&gt; <command>dialplan show</command> - Show current dialplan
407         </para>
408         <para>
409         http://www.asterisk.org - The Asterisk Home Page
410         </para>
411         <para>
412         http://www.asteriskdocs.org - The Asterisk Documentation Project
413         </para>
414         <para>
415         http://wiki.asterisk.org - The Asterisk Wiki
416         </para>
417         <para>
418         http://www.digium.com/ - Asterisk sponsor and hardware supplier
419         </para>
420 </refsect1>
421 <refsect1>
422         <title>AUTHOR</title>
423         <para>
424         <author>
425                 <firstname>Mark Spencer &lt;markster@digium.com&gt;</firstname> 
426         </author>
427         </para>
428         <para>
429         <author>
430                 <firstname>Countless other contributors, see CREDITS with distribution for more information.</firstname> 
431         </author>
432         </para>
433 </refsect1>
434 </refentry>