Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 235 lines (200 sloc) 7.532 kB
639b7c2 @klacke ""
authored
1 .TH YAWS "1" "" "" "User Commands"
2 .SH NAME
3 yaws \- yet another webserver
4 .SH SYNOPSIS
5 .B yaws
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
6 [\fIOPTIONS\fR]
639b7c2 @klacke ""
authored
7 .SH DESCRIPTION
8 .\" Add any additional description here
9 .PP
10 Yaws is fast lightweight webserver. It can run as daemon or
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
11 in interactive mode where it is possible to directly interact
639b7c2 @klacke ""
authored
12 with the webserver. Yaws is particularly good at generating
13 dynamic content. See the user docs for more information on that topic.
14
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
15 .SH DEAMON/SERVER options
16
17
639b7c2 @klacke ""
authored
18 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
19 \fB\-i | --interactive\fR
639b7c2 @klacke ""
authored
20 Interactive mode. This will start yaws in interactive mode with an erlang
21 prompt. All error_logger messages will be written to the tty as well in this
22 mode. Use this when developing yaws code.
23 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
24 \fB\-w | --winteractive\fR
25 Cygwin inteactive mode (werl)
814bae1 @klacke cleaned up the redirect feature. It was poorly implemented and poorly…
authored
26 .TP
27 \fB\-D | --daemon\fR
639b7c2 @klacke ""
authored
28 Daemon mode. This will start yaws as a daemon.
29 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
30 \fB\--heart\fR
a2a82e3 Added the -heart switch
Tobbe Tornquist authored
31 This will cause the yaws system to be automatically restarted
2ba5805 @vinoski add new --heart-restart option to allow control over heart restarts
vinoski authored
32 in case it should crash. This switch also requires the \fI--daemon\fR
a2a82e3 Added the -heart switch
Tobbe Tornquist authored
33 switch to be present.
34 .TP
2ba5805 @vinoski add new --heart-restart option to allow control over heart restarts
vinoski authored
35 \fB\--heart-restart=C,T\fR
36 This controls the number of restarts in a given time period that heart
37 tolerates before refusing to restart Yaws. By default, heart allows up
38 to 5 restarts within a 60 second period before refusing to restart
39 Yaws again. This option allows up to \fIC\fR restarts in \fIT\fR
40 seconds instead. To allow infinite restarts, set both \fIC\fR and
41 \fIT\fR to 0. This switch automatically enables the \fI--heart\fR
42 switch.
43 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
44 \fB\--debug\fR
2ba5805 @vinoski add new --heart-restart option to allow control over heart restarts
vinoski authored
45 Debug mode. This will produce some auxiliary error output for some
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
46 error conditions. It will also start the otp sasl lib for additional
47 error printouts.
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
48 .TP
49 \fB\--nodebug\fR
50 Non-debug mode. This is useful for running interactively via the
51 \FI-i\fR option but without incurring the performance penalties of
52 debug mode.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
53
639b7c2 @klacke ""
authored
54 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
55 \fB\--conf file\fR
639b7c2 @klacke ""
authored
56 Use a different configuration file than the default. The default configuration file
49fc86f @klacke docs and also don't fail if authmod:get_headers() don't exist
authored
57 when running as root is /etc/yaws/yaws.conf. When running as a non priviliged user, yaws
639b7c2 @klacke ""
authored
58 will search for its configuration file in the following order. First in
49fc86f @klacke docs and also don't fail if authmod:get_headers() don't exist
authored
59 $HOME/yaws.conf, then in ./yaws.conf and finally in /etc/yaws/yaws.conf
639b7c2 @klacke ""
authored
60 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
61 \fB\--runmod module\fR
22fd788 Added the '-r <Mod>' switch.
Tobbe Tornquist authored
62 Tells yaws to call \fImodule:start/0\fR at startup. This makes it possible
63 to startup user specific applications together with yaws.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
64
65 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
66 \fB\--pa path\fR
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
67 Add path to the yaws system search path
68
22fd788 Added the '-r <Mod>' switch.
Tobbe Tornquist authored
69 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
70 \fB\--tracetraf\fR
639b7c2 @klacke ""
authored
71 Traffic trace mode. All traffic will be written to a trace file called trace.traffic
72 in the log directory.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
73
639b7c2 @klacke ""
authored
74 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
75 \fB\--tracehttp\fR
639b7c2 @klacke ""
authored
76 HTTP trace mode. All HTTP messages will be written to a trace file called trace.http
77 in the log directory.
82d6e29 @klacke added -x flag for tty trace and did the 1.3 release
authored
78
79 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
80 \fB\--traceout\fR
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
81 When yaws is put into trace mode using either --tracetraf or --tracehttp, traces are written to files. If we provide the --traceout flag, the trace will also be written to stdout.
82d6e29 @klacke added -x flag for tty trace and did the 1.3 release
authored
82
c7c87a4 @klacke -sname and mnesia flag added to start script
authored
83 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
84 \fB\--trace\fR
85 Sames as --tracetraf --traceout. I.e. trace everything and write to stdout.
86
87 .TP
88 \fB\--mnesiadir dir\fR
c7c87a4 @klacke -sname and mnesia flag added to start script
authored
89 Start Mnesia in directory <dir>
90
91 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
92 \fB\--sname xxx\fR
c7c87a4 @klacke -sname and mnesia flag added to start script
authored
93 Start yaws as a distributed erlang node with name <xxx>
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
94 using the unqualified hostname as nodename postfix
95
96 .TP
a90bd68 @klacke added kpoll as default
authored
97 \fB\--disable-kpoll\fR
98 By default, yaws starts erlang with \fI+K true\fR. This flag
99 reverses that.
100
101 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
102 \fB\--name xxx\fR
103 Start yaws as a distributed erlang node with name <xxx> using the
104 fully qualified hostname as nodename postfix
82d6e29 @klacke added -x flag for tty trace and did the 1.3 release
authored
105
37e9d70 @klacke -erlarg patch by Fredrik Thulin
authored
106 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
107 \fB\--proto_dist Mod\fR
37e9d70 @klacke -erlarg patch by Fredrik Thulin
authored
108 Use module Mod for erlang distribution. This is typically only used
109 when we want to run erlang distribution over SSL.
110
111 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
112 \fB\--erlarg STRING\fR
fd5e602 @vinoski Augment yaws man page with --erlarg argument quoting info
vinoski authored
113 Pass STRING as an additional argument to the "erl" program. If STRING
114 comprises multiple words, you must quote it so that your shell passes
115 it to yaws as a single argument. If STRING contains any single quote
116 characters, you must quote each of them as well. For example, to pass
117 the option \fI-env NAME O'Keeffe\fR to "erl" from a Bourne-compatible
118 shell:
119 .PP
120 .nf
121 .ce
122 --erlarg "-env NAME O\\'Keeffe"
123 .fi
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
124
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
125 .TP
126 \fB\--id ID\fR
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
127 This flag sets the id. If we're starting a daemon (or an interactive
128 system) it gives the Yaws server the identity ID. This means that the
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
129 server will write all internal files into the directory
d63642e @vinoski do not pass the --id option if the default id is used
vinoski authored
130 $HOME/.yaws/yaws/ID.
c9778e0 @klacke added support for 2 additional configure
authored
131
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
132 Yaws also creates a file called
c9778e0 @klacke added support for 2 additional configure
authored
133 ${VARDIR}/run/yaws/ctl-${ID} which contains the portnumber the daemon
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
134 is listening on for control request by the control command such
135 as "yaws --hup" etc.
136
137 If we're invoking a control command which should perform some
c9778e0 @klacke added support for 2 additional configure
authored
138 control function on the daemon, we may have to give the --id flag also
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
139 to the control command. If we don't do this the control command
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
140 may interact with the wrong daemon due to finding the wrong "ctl" file.
141
142 The daemon may also optionally specify the "id" in the yaws.conf
143 configuration file.
144
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
145 .SH CONTROL OPTIONS
146 .PP
147 The following list of options are are used to control the daemon
148 from the "outside" while it is running.
149
639b7c2 @klacke ""
authored
150 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
151 \fB\--hup [--id ID]\fR
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
152 HUP the daemon. This forces the daemon to reread the configuration file.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
153 It also makes
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
154 the daemon empty all its internal content caches.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
155 Hence when updating the doc root,
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
156 HUPing the daemon is the fastest way to see the content updates.
639b7c2 @klacke ""
authored
157 .TP
674c8b3 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored
158 \fB\--stop [--id id]\fR
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
159 Stop the daemon (called id)
639b7c2 @klacke ""
authored
160 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
161 \fB\--ls \fR
162 Lists current ids and status of all yaws servers on localhost. In practice this
d63642e @vinoski do not pass the --id option if the default id is used
vinoski authored
163 amounts to a listdir in $HOME/.yaws/yaws - and check whether the different
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
164 systems who has created files there are alive.
d659ba3 @klacke added a 'yaws -ls' command that lists all yaws servers on localhost
authored
165 .TP
674c8b3 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored
166 \fB--status [--id id]\fR
6155cc4 @carsten3347 -S, -load, -check
carsten3347 authored
167 Query a running yaws daemon for its status, and print it.
168 .TP
abe2833 @klacke minor docs for new stats feature
authored
169 \fB--stats [--id id]\fR
170 Query a running yaws daemon for its statistics, and print it.
171 .TP
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
172 \fB--load Modules [--id id]\fR
6155cc4 @carsten3347 -S, -load, -check
carsten3347 authored
173 Try to (re)load erlang modules into a running daemon. This is useful
174 after modifying appmods or modules used by scripts.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
175
176 .TP
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
177 \fB--debug-dump [--id id]\fR
178 Produce a debug dump on stdout. In particular this code lists what
5207102 @klacke Added debug dump functionality
authored
179 we refer to as suspicious processes. I.e. processes that might be
180 hanging or processes that are "large" - hardcoded to 40k words.
181
182 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
183 \fB--ctltrace [--id ID] http | traffic | off\fR
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
184 Control the trace capabilities of a running yaws daemon. If the
185 http or traffic option is given, the daemon will write a log
186 for debug purposes into the logdir.
187
ddf3bee @klacke preparing for 1.78
authored
188 .TP
2ba5805 @vinoski add new --heart-restart option to allow control over heart restarts
vinoski authored
189 \fB--wait-started[=T] [--id ID] \fR
ddf3bee @klacke preparing for 1.78
authored
190 Waits at most 5 seconds for the server to start. Exits with 0 if
2ba5805 @vinoski add new --heart-restart option to allow control over heart restarts
vinoski authored
191 server is running, 1 otherwise. Typically useful in test scripts. The
192 default 5 seconds can be modified by appending \fI=T\fR to the option,
193 where \fIT\fR is the desired number of seconds to wait for the server
194 to start.
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
195
196 .SH MISC OPTIONS
197
6155cc4 @carsten3347 -S, -load, -check
carsten3347 authored
198 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
199 \fB--check YawsFile [IncDirs ....]\fR
200 Test compile a `.yaws' file. Useful in Makefiles when we want to ensure
201 that all .yaws files are syntactically correct
6155cc4 @carsten3347 -S, -load, -check
carsten3347 authored
202 .TP
92bafb4 @klacke removed the ability change userid, also stopped writing to /tmp/yaws …
authored
203 \fB\--version\fR
639b7c2 @klacke ""
authored
204 output version information and exit
5f13a9c @klacke Two patches by Joseph Wayen Norton, one dbg-bug and one providing bet…
authored
205
206 .SH ENVIRONMENT VARIABLES
207 .TP
208 \fBHOME\fR
209 Is used to determine where we write the temporary files. By default
210 all tmp files end up in $HOME/.yaws. This includes the JIT files
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
211 that are the result of processed .yaws files and also the so called
5f13a9c @klacke Two patches by Joseph Wayen Norton, one dbg-bug and one providing bet…
authored
212 control file that is used by the daemon to write the port number
213 to which it is listening for control commands such as "yaws --status"
214
215 Thus HOME is the handle we use in the control commands to
216 find the control file so that we know where to connect to.
217
218 .TP
219 \fBYAWSHOME\fR
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
220 Can be used to override the HOME variable. This is useful when we
5f13a9c @klacke Two patches by Joseph Wayen Norton, one dbg-bug and one providing bet…
authored
221 for example are running yaws under port binding programs such as
222 authpriv.
223
224 It's useful by distros that don't want Yaws to write any files
3a6c4c2 @vinoski document yaws --nodebug option
vinoski authored
225 ever in the HOME directory of root.
5f13a9c @klacke Two patches by Joseph Wayen Norton, one dbg-bug and one providing bet…
authored
226
227
228
639b7c2 @klacke ""
authored
229 .SH AUTHOR
230 Written by Claes Wikstrom
231 .SH "SEE ALSO"
232 .BR yaws.conf (5)
233 .BR erl (1)
234
Something went wrong with that request. Please try again.