Documentation: doc fixes across various parts of the code for ASTERISK issues 23061...
[asterisk/asterisk.git] / doc / asterisk.8
1 '\" -*- coding: us-ascii -*-
2 .if \n(.g .ds T< \\FC
3 .if \n(.g .ds T> \\F[\n[.fam]]
4 .de URL
5 \\$2 \(la\\$1\(ra\\$3
6 ..
7 .if \n(.g .mso www.tmac
8 .TH "asterisk " 8 2011-02-08 "asterisk Trunk" ""
9 .SH NAME
10 asterisk
11 \- All-purpose telephony server. 
12 .SH SYNOPSIS
13 'nh
14 .fi
15 .ad l
16 \fBasterisk\fR \kx
17 .if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
18 'in \n(.iu+\nxu
19 [\fB\-BcdfFghiImnpqRtTvVW\fR] [\fB\-C \fR\fIfile\fR] [\fB\-e \fR\fImemory\fR] [\fB\-G \fR\fIgroup\fR] [\fB\-L \fR\fIloadaverage\fR] [\fB\-M \fR\fIvalue\fR] [\fB\-U \fR\fIuser\fR] [\fB\-s \fR\fIsocket\-file\fR]
20 'in \n(.iu\-\nxu
21 .ad b
22 'hy
23 'nh
24 .fi
25 .ad l
26 \fBasterisk \-r\fR \kx
27 .if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
28 'in \n(.iu+\nxu
29 [\fB\-v\fR] [\fB\-d\fR] [\fB\-x \fR\fIcommand\fR]
30 'in \n(.iu-\nxu
31 .ad b
32 'hy
33 'nh
34 .fi
35 .ad l
36 \fBasterisk \-R\fR \kx
37 .if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
38 'in \n(.iu+\nxu
39 [\fB\-v\fR] [\fB\-d\fR] [\fB\-x \fR\fIcommand\fR]
40 'in \n(.iu-\nxu
41 .ad b
42 'hy
43 .SH DESCRIPTION
44 \fBasterisk\fR is a full-featured telephony server which
45 provides Private Branch eXchange (PBX), Interactive Voice Response (IVR),
46 Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, 
47 Conferencing, and a plethora of other telephony applications to a broad
48 range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny,
49 H.323, Unistim) devices (both endpoints and proxies), as well as traditional TDM
50 hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart,
51 ISDN BRI and many more.
52 .PP
53 At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration
54 file and locates the rest of the configuration files from the configuration
55 in that file. The \-C option specifies an alternate main configuration file.
56 Virtually all aspects of the operation of asterisk's configuration files
57 can be found in the sample configuration files. The format for those files
58 is generally beyond the scope of this man page.
59 .PP
60 When running with \fB\-c\fR, \fB\-r\fR or \fB\-R\fR
61 options, Asterisk supplies a powerful command line, including command
62 completion, which may be used to monitors its status, perform a variety
63 of administrative actions and even explore the applications that are
64 currently loaded into the system.
65 .PP
66 Asterisk is a trademark of Digium, Inc.
67 .SH OPTIONS
68 Running Asterisk starts the asterisk daemon (optionally running it
69 in the foreground). However running it with \*(T<\fB\-r\fR\*(T> or
70 \*(T<\fB\-R\fR\*(T> connects to an existing Asterisk instance through
71 a remote console.
72 .TP 
73 \-B
74 Force the background of the terminal to be black, in order for
75 terminal colors to show up properly. Equivalent to
76 \*(T<\fBforceblackbackground = yes\fR\*(T> in
77 \*(T<\fIasterisk.conf\fR\*(T>. See also
78 \*(T<\fB\-n\fR\*(T> and \*(T<\fB\-W\fR\*(T>.
79 .TP 
80 \-C \fIfile\fR
81 Use \*(T<\fIfile\fR\*(T> as master configuration file
82 instead of the default, /etc/asterisk/asterisk.conf
83 .TP 
84 \-c
85 Provide a control console on the calling terminal. The
86 console is similar to the remote console provided by
87 \*(T<\fB\-r\fR\*(T>. Specifying this option implies 
88 \fB\-f\fR and will cause asterisk to no longer 
89 fork or detach from the controlling terminal. Equivalent 
90 to \*(T<\fBconsole = yes\fR\*(T> in \*(T<\fIasterisk.conf\fR\*(T>.
91 .TP 
92 \-d
93 Enable extra debugging statements. This parameter may be used several
94 times, and each increases the debug level. Equivalent to \*(T<\fBdebug = \fR\*(T>\fInum\fR
95 in \*(T<\fIasterisk.conf\fR\*(T> to explicitly set the initian debug
96 level to \fInum\fR. When given at startup, this
97 option also implies \*(T<\fB\-f\fR\*(T> (no forking). However when
98 connecting to an existing Asterisk instance (\*(T<\fB\-r\fR\*(T> or
99 \*(T<\fB\-R\fR\*(T>), it may only increase the debug level.
100 .TP 
101 -e \fImemory\fR
102 Limit the generation of new channels when the amount of free memory 
103 has decreased to under \fImemory\fR megabytes.
104 Equivalent to \*(T<\fBminmemfree = \fR\*(T>\fImemory\fR in
105 \*(T<\fIasterisk.conf\fR\*(T>.
106 .TP 
107 \-f
108 Do not fork or detach from controlling terminal. Overrides any
109 preceding specification of \fB\-F\fR on the command line.
110 Equivalent to \*(T<\fBnofork = yes\fR\*(T> in \*(T<\fIasterisk.conf\fR\*(T>.
111 See also \*(T<\fB\-c\fR\*(T>.
112 .TP 
113 \-F
114 Always fork and detach from controlling terminal. Overrides any
115 preceding specification of \fB\-f\fR on the command line.
116 May also be used to prevent \*(T<\fB\-d\fR\*(T> and \*(T<\fB\-v\fR\*(T> to imply
117 no forking. Equivalent to \*(T<\fBalwaysfork = yes\fR\*(T> in \*(T<\fIasterisk.conf\fR\*(T>.
118 .TP 
119 \-g
120 Remove resource limit on core size, thus forcing Asterisk to dump
121 core in the unlikely event of a segmentation fault or abort signal.
122 \fBNOTE:\fR in some cases this may be incompatible
123 with the \fB\-U\fR or \fB\-G\fR flags.
124 .TP 
125 \-G \fIgroup\fR
126 Run as group \fIgroup\fR instead of the
127 calling group. \fBNOTE:\fR this requires substantial work
128 to be sure that Asterisk's environment has permission to write
129 the files required for its operation, including logs, its comm
130 socket, the asterisk database, etc.
131 .TP 
132 \-h
133 Provide brief summary of command line arguments and terminate.
134 .TP 
135 \-i
136 Prompt user to intialize any encrypted private keys for IAX2
137 secure authentication during startup.
138 .TP 
139 \-I
140 Enable internal timing if DAHDI timing is available.
141 The default behaviour is that outbound packets are phase locked
142 to inbound packets. Enabling this switch causes them to be
143 locked to the internal DAHDI timer instead.
144 .TP 
145 \-L \fIloadaverage\fR
146 Limits the maximum load average before rejecting new calls. This can
147 be useful to prevent a system from being brought down by terminating
148 too many simultaneous calls.
149 .TP 
150 \-m
151 Temporarily mutes output to the console and logs. To return to normal,
152 use \fBlogger mute\fR.
153 .TP 
154 \-M \fIvalue\fR
155 Limits the maximum number of calls to the specified value. This can
156 be useful to prevent a system from being brought down by terminating
157 too many simultaneous calls.
158 .TP 
159 \-n
160 Disable ANSI colors even on terminals capable of displaying them.
161 .TP 
162 \-p
163 If supported by the operating system (and executing as root),
164 attempt to run with realtime priority for increased performance and
165 responsiveness within the Asterisk process, at the expense of other
166 programs running on the same machine.
167
168 Note: \fBastcanary\fR will run concurrently with
169 \fBasterisk\fR. If \fBastcanary\fR stops
170 running or is killed, \fBasterisk\fR will slow down to
171 normal process priority, to avoid locking up the machine.
172 .TP 
173 \-q
174 Reduce default console output when running in conjunction with
175 console mode (\fB\-c\fR).
176 .TP 
177 \-r
178 Instead of running a new Asterisk process, attempt to connect
179 to a running Asterisk process and provide a console interface
180 for controlling it.
181 .TP 
182 \-R
183 Much like \fB\-r\fR. Instead of running a new Asterisk process, attempt to connect
184 to a running Asterisk process and provide a console interface
185 for controlling it. Additionally, if connection to the Asterisk 
186 process is lost, attempt to reconnect for as long as 30 seconds.
187 .TP 
188 \-s \fIsocket file name\fR
189 In combination with \fB\-r\fR, connect directly to a specified
190 Asterisk server socket.
191 .TP 
192 \-t
193 When recording files, write them first into a temporary holding directory, 
194 then move them into the final location when done.
195 .TP 
196 \-T
197 Add timestamp to all non-command related output going to the console
198 when running with verbose and/or logging to the console.
199 .TP 
200 \-U \fIuser\fR
201 Run as user \fIuser\fR instead of the
202 calling user. \fBNOTE:\fR this requires substantial work
203 to be sure that Asterisk's environment has permission to write
204 the files required for its operation, including logs, its comm
205 socket, the asterisk database, etc.
206 .TP 
207 \-v
208 Increase the level of verboseness on the console. The more times
209 \fB\-v\fR is specified, the more verbose the output is.
210 Specifying this option implies \fB\-f\fR and will cause
211 asterisk to no longer fork or detach from the controlling terminal.
212 This option may also be used in conjunction with \fB\-r\fR
213 and \fB\-R\fR.
214
215 Note: This always sets the verbose level in the asterisk process,
216 even if it is running in the background. This will affect the size
217 of your log files.
218 .TP 
219 \-V
220 Display version information and exit immediately.
221 .TP 
222 \-W
223 Display colored terminal text as if the background were white
224 or otherwise light in color. Normally, terminal text is displayed
225 as if the background were black or otherwise dark in color.
226 .TP 
227 \-x \fIcommand\fR
228 Connect to a running Asterisk process and execute a command on
229 a command line, passing any output through to standard out and
230 then terminating when the command execution completes. Implies
231 \fB\-r\fR when \fB\-R\fR is not explicitly
232 supplied.
233 .TP 
234 \-X
235 Enables executing of includes via \fB#exec\fR directive.
236 This can be useful if You want to do \fB#exec\fR inside
237 \*(T<\fIasterisk.conf\fR\*(T>
238 .SH EXAMPLES
239 \fBasterisk\fR - Begin Asterisk as a daemon
240 .PP
241 \fBasterisk \-vvvgc\fR - Run on controlling terminal
242 .PP
243 \fBasterisk \-rx "core show channels"\fR - Display channels on running server
244 .SH BUGS
245 Bug reports and feature requests may be filed at https://issues.asterisk.org
246 .SH "SEE ALSO"
247 http://www.asterisk.org - The Asterisk Home Page
248 .PP
249 http://www.asteriskdocs.org - The Asterisk Documentation Project
250 .PP
251 http://wiki.asterisk.org - The Asterisk Wiki
252 .PP
253 http://www.digium.com/ - Asterisk is sponsored by Digium
254 .SH AUTHOR
255 Mark Spencer <markster@digium.com>
256 .PP
257 Countless other contributors, see CREDITS with distribution for more information.