YAWS(1)

💖 YAWS(1) — like, the manual page for yaws, bestie 💖

okay so first things first: this is page YAWS(1) from the User Commands part of the manual, and the command is literally called yaws, which stands for "yet another webserver" (iconic name, no notes). grab a lil snack, we're going through every single flag together 🍓

---

✨ NAME ✨

yaws — yet another webserver 🦋

---

🌸 SYNOPSIS 🌸

yaws [OPTIONS]

that's it. that's the whole vibe. options go in, server comes out 💅

---

👑 DESCRIPTION 👑

Yaws is a fast lightweight webserver. fr fr, that's the whole pitch and it delivers.

It can run as a daemon or in interactive mode, and in interactive mode you can literally talk to the webserver directly, like a little conversation, so cute 🫶

Yaws is particularly good at generating dynamic content. See the user docs for more info on that topic, because that's a whole other adventure bestie.

---

🧚 DAEMON/SERVER options 🧚

• -i | --interactive — interactive mode, babes. This starts yaws in interactive mode with an erlang prompt. Also, all error_logger messages get written to the tty in this mode too. Use this when you're developing yaws code. 👑
• -w | --winteractive — Cygwin inteactive mode (werl). (yes the typo is theirs, we keep it, periodt)
• -D | --daemon — daemon mode. This starts yaws as a daemon. bye bestie, we're backgrounding you 💅
• --heart — this makes the yaws system automatically restart itself if it crashes. And heads up: this switch also requires the --daemon switch to be present. no daemon, no heart, that's the rule.
• --heart-restart=C,T — this controls how many restarts in a given time period that heart tolerates before it flat-out refuses to restart Yaws. By default, heart allows up to 5 restarts within a 60 second period before refusing to restart Yaws again. This option lets you do up to C restarts in T seconds instead. Wanna allow infinite restarts? Set both C and T to 0. And btw, this switch automatically enables the --heart switch. it just does that.
• --debug — debug mode. This produces some auxiliary error output for some error conditions. It also starts the otp sasl lib for additional error printouts. extra chatter, we love her 🙈
• --nodebug — non-debug mode. Super useful for running interactively via the -i option but without incurring the performance penalties of debug mode. all the vibes, none of the lag ✨
• --conf file — use a different configuration file than the default. If the configuration parameter config is set, yaws uses it as the default configuration file. Else, the default configuration file when running as root is /etc/yaws/yaws.conf. When running as a non-priviliged user, yaws searches for its configuration file in this order: first in $HOME/yaws.conf, then in ./yaws.conf, and finally in /etc/yaws/yaws.conf. it's giving scavenger hunt 🔍
• --runmod module — tells yaws to call module:start/0 at startup. This makes it possible to start up user-specific applications together with yaws. bring your friends to the party 🎀
• --pa path — add path to the yaws system search path.
• --tracetraf — traffic trace mode. All traffic gets written to a trace file called trace.traffic in the log directory. 👀
• --tracehttp — HTTP trace mode. All HTTP messages get written to a trace file called trace.http in the log directory.
• --traceout — 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. double the tea ☕
• --trace — same as --tracetraf --traceout. I.e. trace everything and write to stdout. maximalist behaviour, respect.
• --mnesiadir dir — start Mnesia in directory <dir>.
• --sname xxx — start yaws as a distributed erlang node with name <xxx> using the unqualified hostname as nodename postfix.
• --disable-kpoll — by default, yaws starts erlang with +K true. This flag reverses that. flipping the switch, bestie.
• --name xxx — start yaws as a distributed erlang node with name <xxx> using the fully qualified hostname as nodename postfix. (yes this is the sibling of --sname, they're twins, one's just more formal 💅)
• --proto_dist Mod — use module Mod for erlang distribution. This is typically only used when we want to run erlang distribution over SSL. fancy 🔒
• --erlarg STRING — pass STRING as an additional argument to the erl program. If STRING comprises multiple words, you must quote it so that your shell passes it to yaws as a single argument. If STRING contains any single quote characters, you must quote each of them as well. For example, to pass the option -env NAME O'Keeffe to erl from a Bourne-compatible shell:

--erlarg "-env NAME O\'Keeffe"

ok this one's fiddly, so read it twice bestie. quoting is not optional here, the shell will absolutely betray you otherwise 😭

• --id ID — this flag sets the id. If we're starting a daemon (or an interactive system), it gives the Yaws server the identity ID. This means the server will write all internal files into the directory $HOME/.yaws/yaws/ID.

Yaws also creates a file called $HOME/.yaws/yaws/ID/CTL which contains the portnumber the daemon is listening on for control requests by the control command such as yaws --hup etc.

If we're invoking a control command which should perform some control function on the daemon, we may have to give the --id flag also to the control command. If we don't do this, the control command may interact with the wrong daemon due to finding the wrong ctl file. 💀

The daemon may also optionally specify the id in the yaws.conf configuration file.

• --umask MASK — set the umask for the daemon to MASK.
• --encoding latin|unicode — set the config file encoding (default: latin1).

---

🎀 CONTROL OPTIONS 🎀

The following list of options are used to control the daemon from the "outside" while it is running. like remote-controlling your bestie from across the room 🫶

• --hup [--id ID] — HUP the daemon. This forces the daemon to reread the configuration file. It also makes the daemon empty all its internal content caches. Hence when updating the doc root, HUPing the daemon is the fastest way to see the content updates. refresher moment ✨
• --stop [--id id] — stop the daemon (called id). go to sleep bb 😴
• --ls — lists current ids and status of all yaws servers on localhost. In practice this amounts to a listdir in $HOME/.yaws/yaws — and check whether the different systems who have created files there are alive. lil headcount 💅
• --status [--id id] — query a running yaws daemon for its status, and print it.
• --stats [--id id] — query a running yaws daemon for its statistics, and print it. numbers, we love numbers 🍓
• --running-config [--id id] — query a running yaws daemon for its current configuration, and print it. This can be useful when attempting to figure out how to set config in embedded mode. Configure yaws to your liking in non-embedded mode, run this command, and use the output to populate the embedded mode records. chef's kiss shortcut 👑
• --load Modules [--id id] — try to (re)load erlang modules into a running daemon. This is useful after modifying appmods or modules used by scripts. hot reload, no restart, that's the dream 🦋
• --debug-dump [--id id] — produce a debug dump on stdout. In particular this code lists what we refer to as suspicious processes. I.e. processes that might be hanging or processes that are "large" — hardcoded to 40k words. 👀 sus.
• --ctltrace [--id ID] http | traffic | off — control the trace capabilities of a running yaws daemon. If the http or traffic option is given, the daemon will write a log for debug purposes into the logdir.
• --wait-started[=T] [--id ID] — waits at most 30 seconds for the server to start. Exits with 0 if the server is running, 1 otherwise. Typically useful in test scripts. The default 30 seconds can be modified by appending =T to the option, where T is the desired number of seconds to wait for the server to start. we are ✨patient✨ but only for 30 seconds by default.

---

🌈 MISC OPTIONS 🌈

• --check YawsFile [IncDirs ....] — test compile a .yaws file. Useful in Makefiles when we want to ensure that all .yaws files are syntactically correct. syntax check bestie, no surprises 💖
• --version — output version information and exit.

---

🦋 ENVIRONMENT VARIABLES 🦋

• HOME — is used to determine where we write the temporary files. By default all tmp files end up in $HOME/.yaws. This includes the JIT files that are the result of processed .yaws files and also the so called control file that is used by the daemon to write the port number to which it is listening for control commands such as yaws --status.

Thus HOME is the handle we use in the control commands to find the control file so that we know where to connect to. it's the group chat pin 📌

• YAWSHOME — can be used to override the HOME variable. This is useful when we for example are running yaws under port binding programs such as authpriv.

It's useful by distros that don't want Yaws to write any files ever in the HOME directory of root. respect the boundaries 🫶

---

💜 AUTHOR 💜

Written by Claes Wikstrom. ty king 👑

---

⭐ SEE ALSO ⭐

yaws.conf(5) erl(1)

go read those too, iykyk 💅

---

🌸 okay that's the whole page bestie, every flag, every default, every warning, nothing skipped, no cap 🌸

and a lil sign-off: this was page YAWS(1) from the User Commands manual — go forth and serve some dynamic content, you main character 🎀💖✨