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