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