diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2023-10-24 14:20:39 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2023-10-24 14:20:39 +0000 |
| commit | bf90fbf8686fe7e0ea9b86fd13457e860a8ab89d (patch) | |
| tree | 99bb4b74db1812acfa6912a9f0b99d3e0da434b4 | |
| parent | 713994fd2c7a6da9e69222695e7d7a1e963312f8 (diff) | |
| download | tipidee-bf90fbf8686fe7e0ea9b86fd13457e860a8ab89d.tar.gz tipidee-bf90fbf8686fe7e0ea9b86fd13457e860a8ab89d.tar.xz tipidee-bf90fbf8686fe7e0ea9b86fd13457e860a8ab89d.zip | |
Some doc modifications
Signed-off-by: Laurent Bercot <ska@appnovation.com>
| -rw-r--r-- | doc/faq.html | 93 | ||||
| -rw-r--r-- | doc/index.html | 7 | ||||
| -rw-r--r-- | doc/quickstart.html | 70 | ||||
| -rw-r--r-- | doc/tipidee-config.html | 2 |
4 files changed, 101 insertions, 71 deletions
diff --git a/doc/faq.html b/doc/faq.html new file mode 100644 index 0000000..d2594f6 --- /dev/null +++ b/doc/faq.html @@ -0,0 +1,93 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>tipidee: FAQ</title> + <meta name="Description" content="tipidee: FAQ" /> + <meta name="Keywords" content="tipidee FAQ caveats frequently asked questions" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">tipidee</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> tipidee caveats and FAQ </h1> + +<div id="caveats"> +<h2> Caveats </h2> +</div> + +<h3> <tt>Host</tt> support in HTTP/1.0 </h3> + +<p> + A strict reading of the +<a href="https://datatracker.ietf.org/doc/html/rfc1945">HTTP/1.0 specification</a> +says that the Request-Line is the only piece of client-provided data that can +be used to identify a resource, and that extension headers can modify the +interpretation and processing of that resource but not <em>change</em> what +resource is served. +</p> + +<p> + This goes directly against the use of the <tt>Host</tt> header to identify +the host of a resource and that is used in HTTP/1.1. +</p> + +<p> + A lot of HTTP servers out there don't care about a strict reading of HTTP/1.0 +(or even a strict reading of anything, really), and have +historically used <tt>Host</tt> to perform virtual hosting even in HTTP/1.0, +even though it goes against the specification. Consequently, clients have +adapted, and +<a href="https://github.com/curl/curl/issues/5976">even the popular +<tt>curl</tt> client</a> sends a <tt>Host</tt> header in HTTP/1.0. +</p> + +<p> + Since the point of the Web is interoperability, tipidee aligns with +the common practice, and will read a client-provided <tt>Host</tt> header, +if any, to determine what domain the request is directed to, even in +HTTP/1.0 no matter what the spec says. I refer to this practice as +"speaking HTTP/1.05". +</p> + +<div id="faq"> +<h2> Frequently asked questions </h2> +</div> + +<h3> I want my web server to listen to more than one address. Do I need +to do all that for every address I have? </h3> + +<p> + Not necessarily: you could listen to <tt>0.0.0.0</tt> for IPv4, and +<tt>::</tt> for IPv6. But if you don't want your server to listen to +<em>all</em> the addresses on your machine, then yes, you will have +to run one process per address:port tuple. +</p> + +<p> + It's okay though: every listening process is very small. The skarnet.org +server has two network cards and runs a web server on both of them, on +IPv4 and IPv6, over HTTP and HTTPS, which makes 8 services. Plus one +<a href="//skarnet.org/software/s6/s6-log.html">s6-log</a> logger process +for each of these services. Plus a supervisor for every service and every +logger — for a whooping total of 64 long-running processes just for +its web server functionality; and it's still not even noticeable, the +amount of resources it consumes is negligible. So, don't worry about it; +all your resources are still available for the serving itself. +</p> + +<p> + Note that this allows you to run different instances of +<a href="tipideed.html">tipideed</a>, on different sockets, with different +configurations, if you need it. Use the <tt>-f</tt> option to specify a +different config file in your instances. +</p> + +</body> +</html> diff --git a/doc/index.html b/doc/index.html index 76971e9..8a27de2 100644 --- a/doc/index.html +++ b/doc/index.html @@ -191,6 +191,13 @@ the previous versions of tipidee and the current one. </li> <li><a href="tipidee.conf.html">The <tt>/etc/tipidee.conf</tt> file format</a></li> </ul> +<h3> Usage notes </h3> + +<ul> +<li> tipidee's <a href="quickstart.html">quickstart guide</a> </li> +<li> A list of <a href="faq.html">caveats and FAQs</a> </li> +</ul> + <h3> Design notes </h3> <ul> diff --git a/doc/quickstart.html b/doc/quickstart.html index 312b87f..3b2ebe6 100644 --- a/doc/quickstart.html +++ b/doc/quickstart.html @@ -103,75 +103,5 @@ your service manager scripts. </li> containing service files to run tipidee under various service managers. </p> -<div id="caveats"> -<h2> Caveats </h2> -</div> - -<h3> <tt>Host</tt> support in HTTP/1.0 </h3> - -<p> - A strict reading of the -<a href="https://datatracker.ietf.org/doc/html/rfc1945">HTTP/1.0 specification</a> -says that the Request-Line is the only piece of client-provided data that can -be used to identify a resource, and that extension headers can modify the -interpretation and processing of that resource but not <em>change</em> what -resource is served. -</p> - -<p> - This goes directly against the use of the <tt>Host</tt> header to identify -the host of a resource and that is used in HTTP/1.1. -</p> - -<p> - A lot of HTTP servers out there don't really care about that, and have -historically used <tt>Host</tt> to perform virtual hosting even in HTTP/1.0, -even though it goes against the specification. Consequently, clients have -adapted, and -<a href="https://github.com/curl/curl/issues/5976">even the popular -<tt>curl</tt> client</a> sends a <tt>Host</tt> header in HTTP/1.0. -</p> - -<p> - Since the point of the Web is interoperability, tipidee aligns with -the common practice, and will read a client-provided <tt>Host</tt> header, -if any, to determine what domain the request is directed to, even in -HTTP/1.0 though it is contrary to the specification. I refer to this -practice as "HTTP/1.05". -</p> - -<div id="faq"> -<h2> Frequently asked questions </h2> -</div> - -<h3> I want my web server to listen to more than one address. Do I need -to do all that for every address I have? </h3> - -<p> - Not necessarily: you could listen to <tt>0.0.0.0</tt> for IPv4, and -<tt>::</tt> for IPv6. But if you don't want your server to listen to -<em>all</em> the addresses on your machine, then yes, you will have -to run one process per address:port tuple. -</p> - -<p> - It's okay though: every listening process is very small. The skarnet.org -server has two network cards and runs a web server on both of them, on -IPv4 and IPv6, over HTTP and HTTPS, which makes 8 services. Plus one -<a href="//skarnet.org/software/s6/s6-log.html">s6-log</a> logger process -for each of these services. Plus a supervisor for every service and every -logger — for a whooping total of 64 long-running processes just for -its web server functionality; and it's still not even noticeable, the -amount of resources it consumes is negligible. So, don't worry about it; -all your resources are still available for the serving itself. -</p> - -<p> - Note that this allows you to run different instances of -<a href="tipideed.html">tipideed</a>, on different sockets, with different -configurations, if you need it. Use the <tt>-f</tt> option to specify a -different config file in your instances. -</p> - </body> </html> diff --git a/doc/tipidee-config.html b/doc/tipidee-config.html index 61b0e8a..9c1ee33 100644 --- a/doc/tipidee-config.html +++ b/doc/tipidee-config.html @@ -128,7 +128,7 @@ tipidee-config is the switch. </li> <p> Just remember to run <tt>tipidee-config</tt> whenever you make -a modification to your config file. It's a healthy habit to form. +a modification to your config file, and you'll be set. </p> </body> |