README revision 229779
150479SpeterSimple_httpd - A small and free Web server 250186Sdwhite 391853Sluigi"Simple_httpd is like /usr/bin/mail is to mail clients, no frills." 491853Sluigi 591853SluigiThis HTTP server can be used in any FreeBSD/PicoBSD application. 691853Sluigi 791853SluigiIt has been tested under FreeBSD 2.2.x, 3.x and 4.x. It might work 891853Sluigion other OS systems, but it's for FreeBSD primarily. 991853Sluigi 1091853SluigiThe main advantage to Simple_httpd is that it is very small. 1150186SdwhiteThe 25K binary can satisfy most needs in a small or embedded 1291853Sluigiappplication. If you want a full featured server see 1391853Sluigi/usr/ports/www/apache* or http://www.apache.org 1450186Sdwhite 1550186SdwhiteSimple_httpd is released under a BSD style copyright that unlike 1650186SdwhiteGPL is embedded developer friendly. 1750186Sdwhite 1850186SdwhiteThe server is designed to be run in one of two modes. The standard 1950186Sdwhitemode is a httpd server running in the background serving up a directory 2050186Sdwhiteof html,gif,cgi whatever. Your traditional www server. 2150186Sdwhite 2250186SdwhiteThe "fetch" mode supports file transfer over httpd. This 2350186Sdwhiteis best thought of as mate for fetch(1). This feature can be 2450186Sdwhiteuseful to transfer a file from one host to another. 2550186Sdwhite 2691853SluigiSimple_httpd has the ability to run CGI scripts. All CGI 2791853Sluigiscripts must be located in ${DOCUMENT_ROOT}/cgi-bin. The 2891853Sluigiserver currently only sets 3 environment variables before calling 2991853Sluigithe script. 3050186Sdwhite 3191853SluigiCGI Environment variables are below: 3250186Sdwhite 3350186SdwhiteSERVER_SOFTWARE = FreeBSD/PicoBSD 3450186SdwhiteREMOTE_HOST = client.canada_lower_taxes.com 3550186SdwhiteREMOTE_ADDR = 200.122.13.108 3650186Sdwhite 3750186SdwhiteIn most target applications for this server the extra DNS traffic from 3850186Sdwhitethe remote_addr lookup will likely be on the local lan anyway and not 3950186Sdwhiteon the other side of the internet. You can turn it off yourself in 4050186Sdwhitethe code if you want to speed the whole process up. Be sure to turn 4150186Sdwhiteit off for the logfile also. 4250186Sdwhite 4350186SdwhiteHow to use it? 4450186Sdwhite============== 4550186Sdwhite 4650186SdwhiteCompile with make, run as follows 4750186Sdwhite 4850186Sdwhiteusage: simple_httpd [-vD] 4950186Sdwhite [-d directory] 5050186Sdwhite [-g grpid] 5150186Sdwhite [-l logfile] 5250186Sdwhite [-p port] 5350186Sdwhiteor 5450186Sdwhiteusage: simple_httpd [-p port] -f filename 5550186Sdwhite 5650186Sdwhite-v 5750186SdwhiteRun the server verbose. Show the program options that will be used for this 5850186Sdwhiteprocess. Will only show information during startup, no messages will 5950186Sdwhitebe displayed while serving requests. In other words you can still 6050186Sdwhitedaemonize without fear of output on stdout. 6150186Sdwhite 6250186Sdwhite-D 6350186SdwhiteDo not daemonize. The server will not run in the background. It will 6450186Sdwhitestay attached to the tty. This is useful for debugging. In this 6550186Sdwhitemode no log file is created. Logging info is to stdout. 6650186Sdwhite 6750186SdwhiteThis option is automatically selected if fetch option is selected. 6891853Sluigi 6991853Sluigi-d directory 7050186SdwhiteThe html document directory, if nothing is provided the default is 7191853Sluigi/httphome if UID is root, otherwise document root is ${HOME}/public_html 7250186Sdwhite 7350186Sdwhite-l logfile 7450186SdwhiteSet the logfile to use. Log messages will be written to /var/log/jhttpd.log 7550186Sdwhiteif you are root and ${HOME}/jhttpd.log otherwise. If you don't want a 7650186Sdwhitelog file try "-l /dev/null" 7750186Sdwhite 7850186Sdwhite-p port 7950186SdwhiteSet the port httpd server will listen to. Default is port 80 if 8050186Sdwhiteyou are root and 1080 if you are not. 8150186Sdwhite 8250186Sdwhite-f filename 8350186SdwhiteThis is the only option needed to use the "fetch" feature. The file 8450186Sdwhitespecified will be the ONLY file served to ANY GET request from a browser 8550186Sdwhiteor fetch(1). 8650186Sdwhite 8750186SdwhiteExample 8850186Sdwhite======= 8950186Sdwhite 9050186SdwhiteStandard Mode: 9150186Sdwhite-------------- 9250186SdwhiteIf you have the FreeBSD handbook installed on your machine and would 9350186Sdwhitelike to serve it up over http for a quick look you could do this 9450186Sdwhite 9550186Sdwhitesimple_httpd -d /usr/share/doc/handbook -l /usr/tmp/jlog.txt -p 1088 -v 9650186Sdwhite 9750186SdwhiteAny browser would be able to look at the handbook with 9850186Sdwhitehttp://whatever_host/handbook.html:1088 9950186Sdwhite 10050186SdwhiteI'm using 1088 as the port since I already have apache running on port 80 10150186Sdwhiteand port 1080 on my host. 10250186Sdwhite 10350186SdwhitePlease note, the handbook is not installed by default in FreeBSD 3.x 10450186SdwhiteIt must be installed from the ports collection first if you want to 10550186Sdwhitetry this. 10650186Sdwhite 10750186SdwhiteAnother simple example is to browse your local ports collection: 10850186Sdwhite 10950186Sdwhitecd /usr/ports 11050186Sdwhitemake readmes #wait about 1 hour! 11150186Sdwhitesimple_httpd -p 1080 -v -d /usr/ports 11250186Sdwhite 11350186SdwhiteThen point your browser at http://whatever_host/README.html 11450186Sdwhite 11550186SdwhiteFetch Mode: 11650186Sdwhite-------------- 11750186SdwhiteThis is designed to be used in conjunction with fetch(3). It allows 11850186Sdwhitefor easy transfer of files from one host to another without messy 11950186Sdwhiteauthentication or pathnames required with ftp. The file to be 12050186Sdwhiteserved up must be readable by the user running simple_httpd. 12150186SdwhiteThis is not a magic way to avoid permissions and read files. 12250186Sdwhite 12350186SdwhiteThe daemon will only serve up ONE file. The file specified will 12450186Sdwhitebe returned for every GET request regardless of what the browser 12550186Sdwhiteasks for. This allows for on the fly naming. 12650186Sdwhite 12791853Sluigisender# simple_httpd -f /usr/tmp/big_file.tgz 12891853Sluigireceiver# fetch http://sender.com/Industrial_Secrets.tgz 12950186Sdwhite 13091853Sluigibig_file.tgz was transferred from one machine to another and renamed 13191853SluigiIndustrial_Secrets.tgz at the same time. 13291853Sluigi 13391853SluigiTunneling over other TCP ports. Choose something that firewall 13491853Sluigiwill probably pass. See /etc/services. 13591853Sluigi 13650186Sdwhitesender# simple_httpd -p 53 -f /usr/tmp/big_file.tgz 13791853Sluigireceiver# fetch http://sender.com:53/Industrial_Secrets.tgz 13891853Sluigi 13991853SluigiTo Do 14091853Sluigi===== 14191853Sluigi 14291853SluigiSimple authentication would be very useful [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$FreeBSD: head/release/picobsd/tinyware/simple_httpd/README 229779 2012-01-07 16:09:43Z uqs $ 168