From 0251ba5cc54cdd24092e442ab7ec364b97d42601 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 21 Sep 2023 05:57:24 +0000 Subject: More doc, complete? Signed-off-by: Laurent Bercot --- doc/tipideed.html | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 176 insertions(+), 4 deletions(-) (limited to 'doc/tipideed.html') diff --git a/doc/tipideed.html b/doc/tipideed.html index b11a63c..0c34af5 100644 --- a/doc/tipideed.html +++ b/doc/tipideed.html @@ -23,7 +23,9 @@ a web server package: it serves files over HTTP.

+

Interface

+
      tipideed [ -v verbosity ] [ -f cdbfile ] [ -d basedir ] [ -R ] [ -U ]
@@ -42,7 +44,9 @@ occurs that makes it nonsensical to keep the connection open. 
 current working directory, one subdirectory for every domain it hosts. 
 
 
+

 
 Common usage 

+

 
 

  tipideed is intended to be run under a TCP super-server such as
@@ -81,11 +85,13 @@ of the tipidee package provides service templates to help you run tipideed under
 s6-rc.
 

 
+

 
 Exit codes 

+

 
 

- 
 0 
 
 Clean exit. The client closed the connection after a stream of
-HTTP exchanges. 

+ 
 0 
 
 Clean exit. There was a successful stream of HTTP exchanges,
+that the client decided to end. 

  
 1 
 
 Illicit client behaviour. tipideed exited because it could
 not serve the client in good faith. 

  
 2 
 
 Illicit CGI script behaviour. tipideed exited because the invoked
@@ -96,12 +102,18 @@ line options, or missing environment variables, etc. 

  
 101 
 
 Cannot happen. This signals a bug in tipideed, and comes with an
 error message asking you to report the bug. Please do so, on the
 skaware mailing-list. 

+ 
 102 
 
 Misconfiguration. tipideed found something in its configuration
+data or in the document layout that it does not like. This can happen, for
+instance, when a document is a symbolic link pointing outside of the server's
+root. 

  
 111 
 
 System call failed. If this happens while serving a request,
 tipideed likely has sent a 500 (Internal Server Error) response to the
 client before exiting. 

 

 
+

 
 Environment variables 

+

 
 
 Reading - mandatory 

 
@@ -173,11 +185,13 @@ otherwise, it will assume it is running plaintext HTTP. 
 so the passed environment is as close as possible to the environment of the
 super-server; and it adds all the variables that are required by the
 CGI 1.1
-specification. It does not add PATH_TRANSLATED, which CGI scripts should
-not rely on.
+specification. As an exception, it does not add PATH_TRANSLATED, which
+cannot be used by CGI scripts in a portable way.
 

 
+

 
 Options 

+

 
 

  
 -v verbosity 

@@ -218,9 +232,150 @@ the super-server has bound to its socket, and all the subsequent operations,
 including the spawning of tipideed processes, are performed as a normal user. 
 

 
+

+
 Document root 

+

+
+

+ The way to organize your documents so they can be served by tipideed
+may look a little weird, but there's a logic to it.
+

+
+

+ tipideed serves documents from subdirectories of its working directory,
+and these subdirectories are named according to the host and
+the port of the request.
+

+
+
    
+ 
  •  A request for https://example.com:1234/doc/u/ment
+will result in a lookup in the filesystem for
+./example.com:1234/doc/u/ment. 
    • 
+ 
  •  A request for https://example.com/doc/u/ment
+will result in a lookup in the filesystem for
+./example.com:443/doc/u/ment. 
    • 
+

+
+

+The fact that the port is always specified allows you to have
+different document sets for the same host on different ports:
+more flexibility.
+

+
+

+ However, most of the time, you don't want different
+document sets for different ports. You want the same document
+sets for ports 80 and 443, and that's it. And you don't want
+to have both a domain example.com:80 section and a
+domain example.com: 443 section in your
+/etc/tipidee.conf, with
+duplicate information.
+

+
+

+ That is why you are allowed to make your document roots
+symbolic links, and resource attributes declared in
+the configuration file are always looked up with the
+canonical path. In other words, the common case
+would be:
+

+
+
    
+ 
  •  Have your document root in ./example.com, a
+real directory. 
    • 
+ 
  •  Declare your resource attributes under a
+domain example.com section in your configuration file. 
    • 
+ 
  •  Have a ./example.com:80 symlink pointing to
+example.com, if you want to serve example.com
+under plaintext HTTP. 
    • 
+ 
  •  Have a ./example.com:80 symlink pointing to
+example.com, if you want to serve example.com
+under HTTPS. 
    • 
+

+
+

+ This system allows you to share documents across virtual hosts
+without fear of misconfiguration. You can symlink any document
+under example.com to any name under example.org;
+if the path via example.com is the canonical path, then
+your resource will still get the correct attributes, defined in a
+domain example.com section, even if it is accessed via an
+example.org URL. You will not inadvertently expose source
+code for CGI scripts, for instance.
+

+
+

+ You can do wild things with symbolic links. However, anything
+that does not resolve to a file in a document root under tipideed's
+current working directory will be rejected. If an attacker symlinks
+your /etc/passwd file, tipideed will keep it safe.
+

+
+
+

 
 Detailed operation 

+

+
+
    
+ 
  •  tipideed reads its compiled
+configuration file. Then:
+ 
      
+  
    •  If the -d option has been given, it changes its working directory. 
      • 
+  
    •  If the -R option has been given, it chroots to its current directory. 
      • 
+  
    •  If the -U option has been given, it drops root privileges. 
      • 
+ 
     
    • 
+ 
  •  It checks that its environment is valid, and that its configuration has
+some minimal defaults it can use. 
    • 
+ 
  •  tipideed listens to a stream of HTTP requests on its standard input. For every
+HTTP request:
+  
      
+   
    •  It parses the request line and check it's HTTP/1.0 or 1.1 
      • 
+   
    •  It parses the headers into a quick access structure 
      • 
+   
    •  It checks header consistency with the request 
      • 
+   
    •  If the method is OPTIONS * or TRACE, it answers here
+and continues the loop 
      • 
+   
    •  It reads the request body, if any 
      • 
+   
    •  It checks in its configuration if a redirection has been defined for
+the wanted resource or a prefix (by directory) of the wanted resource. If it's
+the case, it answers with that redirection and continues the loop. 
      • 
+   
    •  It looks for a suitable resource in the filesystem, completing the
+request with index files if necessary, or substracting CGI INFO_PATHs if
+necessary 
      • 
+   
    •  It uses the canonical path of the resource in the filesystem to look
+for resource attributes in its configuration. (Is this a CGI script? a NPH
+script? Does it have a customized Content-Type? etc.) 
      • 
+   
    •  If the method is a targeted OPTIONS, it answers here and
+continues the loop 
      • 
+   
    •  If the resource is a CGI script:
+    
        
+     
      •  If it is an NPH script, tipideed execs into the script (possibly
+after spawning a helper child if there is a request body to feed to the script)
+with the appropriate environment;
+and the connection will close when the script exits. 
        • 
+     
      •  Else, tipideed spawns the CGI script as a child with the appropriate
+environment, feeds it the request body if any, reads its output, and answers
+the client. 
        • 
+     
      •  If a problem occurs server-side, the client will receive a 502
+answer ("Bad Gateway"), and tipideed will write an error message to
+its stderr, so that administrators can see what went wrong with their setup.
+tipideed trusts its CGI scripts more than its clients, but it does not give
+them its full trust either — lots of sites are running third-party
+backends. 
        • 
+    
       
      • 
+   
    •  Else, the resource is a regular ("static") file, and tipideed serves
+it on its stdout, to the client. 
      • 
+  
     
    • 
+ 
  •  tipideed exits on EOF (when the client closes the connection), or after
+a single HTTP/1.0 request, or when it has answered a request with a
+Connection: close header, or when it encounters an error where it is
+likely that the client will have no use for the connection anymore anyway
+and exiting is simpler and cheaper — in which case tipideed adds
+Connection: close to its last answer. 
    • 
+

 
+

 
 Performance considerations 

+

 
 

  On systems that implement
@@ -264,12 +419,29 @@ other Web servers, please share them on the
 skaware mailing-list.
 

 
+

 
 Notes 

+

 
 
    
+ 
  •  tipideed sometimes answers 400, or even does not answer at all
+(it just exits), when receiving some malformed or weirdly paced
+client requests, despite what the
+HTTP RFC says.
+This is on purpose. HTTP servers are very much solicited, they can run
+very hot, the Web is a cesspool of bots and bad actors, and every
+legitimate browser knows how to speak HTTP properly and without abusing
+corner cases in the protocol.
+It makes no sense to try to follow the book to the letter, expending
+precious resources, when the client can't even be bothered to pretend
+it's legit. Knowing when to exit early is crucial for good resource
+management. 
    • 
  
  •  tipideed is pronounced tipi-deed. You can say
 tipi-dee-dee, but only if you're the type of person who also says
 PC computer, NIC card or ATM machine. 
    • 
+ 
  •  tipidee is the name of the package, the software suite
+implementing a Web server. tipideed is the name of the program
+doing the HTTP serving part. 
    • 
 

 
 
-- 
cgit v1.3.1