release/picobsd/tinyware/simple_httpd/README

   1 Simple_httpd  -  A small and free Web server
   2
   3 "Simple_httpd is like /usr/bin/mail is to mail clients, no frills."
   4
   5 This HTTP server can be used in any FreeBSD/PicoBSD application.
   6
   7 It has been tested under FreeBSD 2.2.x, 3.x and 4.x. It might work
   8 on other OS systems, but it's for FreeBSD primarily.
   9
  10 The main advantage to Simple_httpd is that it is very small.
  11 The 25K binary can satisfy most needs in a small or embedded
  12 appplication.  If you want a full featured server see
  13 /usr/ports/www/apache* or http://www.apache.org
  14
  15 Simple_httpd is released under a BSD style copyright that unlike
  16 GPL is embedded developer friendly.
  17
  18 The server is designed to be run in one of two modes.  The standard
  19 mode is a httpd server running in the background serving up a directory
  20 of html,gif,cgi whatever.  Your traditional www server.
  21
  22 The "fetch" mode supports file transfer over httpd.  This
  23 is best thought of as mate for fetch(1).  This feature can be
  24 usefull to transfer a file from one host to another.
  25
  26 Simple_httpd has the ability to run CGI scripts.  All CGI
  27 scripts must be located in ${DOCUMENT_ROOT}/cgi-bin.  The
  28 server currently only sets 3 enviroment variables before calling
  29 the script.
  30
  31 CGI Enviroment variables are below:
  32
  33 SERVER_SOFTWARE = FreeBSD/PicoBSD
  34 REMOTE_HOST = client.canada_lower_taxes.com
  35 REMOTE_ADDR = 200.122.13.108
  36
  37 In most target applications for this server the extra DNS traffic from
  38 the remote_addr lookup will likely be on the local lan anyway and not
  39 on the other side of the internet.  You can turn it off yourself in
  40 the code if you want to speed the whole process up.  Be sure to turn
  41 it off for the logfile also.
  42
  43 How to use it?
  44 ==============
  45
  46 Compile with make, run as follows
  47
  48 usage: simple_httpd     [-vD]
  49                         [-d directory]
  50                         [-g grpid]
  51                         [-l logfile]
  52                         [-p port]
  53 or
  54 usage: simple_httpd [-p port] -f filename
  55
  56 -v
  57 Run the server verbose.  Show the program options that will be used for this
  58 process.  Will only show information during startup, no messages will
  59 be displayed while serving requests.  In other words you can still
  60 daemonize without fear of output on stdout.
  61
  62 -D
  63 Do not daemonize.  The server will not run in the background.  It will
  64 stay attached to the tty.  This is usefull for debugging.  In this
  65 mode no log file is created.  Logging info is to stdout.
  66
  67 This option is automatically selected if fetch option is selected.
  68
  69 -d directory
  70 The html document directory, if nothing is provided the default is
  71 /httphome if UID is root, otherwise document root is ${HOME}/public_html
  72
  73 -l logfile
  74 Set the logfile to use. Log messages will be written to /var/log/jhttpd.log
  75 if you are root and ${HOME}/jhttpd.log otherwise. If you don't want a
  76 log file try "-l /dev/null"
  77
  78 -p port
  79 Set the port httpd server will listen to.  Default is port 80 if
  80 you are root and 1080 if you are not.
  81
  82 -f filename
  83 This is the only option needed to use the "fetch" feature.  The file
  84 specified will be the ONLY file served to ANY GET request from a browser
  85 or fetch(1).
  86
  87 Example
  88 =======
  89
  90 Standard Mode:
  91 --------------
  92 If you have the FreeBSD handbook installed on your machine and would
  93 like to serve it up over http for a quick look you could do this
  94
  95 simple_httpd -d /usr/share/doc/handbook -l /usr/tmp/jlog.txt -p 1088 -v
  96
  97 Any browser would be able to look at the handbook with
  98 http://whatever_host/handbook.html:1088
  99
 100 I'm using 1088 as the port since I already have apache running on port 80
 101 and port 1080 on my host.
 102
 103 Please note, the handbook is not installed by default in FreeBSD 3.x
 104 It must be installed from the ports collection first if you want to
 105 try this.
 106
 107 Another simple example is to browse your local ports collection:
 108
 109 cd /usr/ports
 110 make readmes   #wait about 1 hour!
 111 simple_httpd -p 1080 -v -d /usr/ports
 112
 113 Then point your browser at http://whatever_host/README.html
 114
 115 Fetch Mode:
 116 --------------
 117 This is designed to be used in conjunction with fetch(3).  It allows
 118 for easy transfer of files from one host to another without messy
 119 authentication or pathnames required with ftp.  The file to be
 120 served up must be readable by the user running simple_httpd.
 121 This is not a magic way to avoid permissions and read files.
 122
 123 The daemon will only serve up ONE file.  The file specified will
 124 be returned for every GET request regardless of what the browser
 125 asks for.  This allows for on the fly naming.
 126
 127 sender# simple_httpd -f /usr/tmp/big_file.tgz
 128 receiver# fetch http://sender.com/Industrial_Secrets.tgz
 129
 130 big_file.tgz was transferred from one machine to another and renamed
 131 Industrial_Secrets.tgz at the same time.
 132
 133 Tunneling over other TCP ports.  Choose something that firewall
 134 will probably pass. See /etc/services.
 135
 136 sender# simple_httpd -p 53 -f /usr/tmp/big_file.tgz
 137 receiver# fetch http://sender.com:53/Industrial_Secrets.tgz
 138
 139 To Do
 140 =====
 141
 142 Simple authentication would be very usefull[understatment].
 143 /etc/passwd or PAM would be nice.
 144
 145 I think a netmask option would be good. Most internet appliances
 146 probably want to restrict traffic to local ethernet anyway.
 147 ie: Allow anything from my class C.
 148
 149 The server always has 1 zombie process hanging around when it
 150 runs as a daemon.  Should fix so that it doesn't happen.
 151
 152 Anything to make it faster!
 153
 154 Man page
 155
 156 If anyone has any improvements or ways to easily implement something
 157 please let me <wlloyd@slap.net> know.  If you make some neat embedded
 158 device with PicoBSD I want to know too!
 159
 160 Credits
 161 =======
 162
 163 This program was originally contributed by Marc Nicholas <marc@netstor.com>
 164
 165 Major rewrite by William Lloyd <wlloyd@slap.net>
 166
 167 $FreeBSD: src/release/picobsd/tinyware/simple_httpd/README,v 1.6 1999/08/28 01:33:59 peter Exp $
 168 $DragonFly: src/release/picobsd/tinyware/simple_httpd/Attic/README,v 1.2 2003/06/17 04:27:20 dillon Exp $