Micro_httpd Web Server on Mac OSX

Rev 1.0

 Brian Mork - Early 2013
© 2013 Increa Technology

Site Index  •  Wiki  • Blog



I was staying in a hotel, and when I queried the hotel's wireless rounter, it responded with a page served up by micro_httpd.  Micro_httpd turned out to be a C program no more than a page or two long.  I decided I wanted to run this tiny web server on my MacBook Pro.  This page describes how to do so.

Install Instructions


Create a directory in your home directory titled "public_html".  You can create an alias to a directory already existing in your home directory using the command "ln -s Public public_html". Create a text file named "index.html" in the public_html directory.  Later you can create a real (fancy) web page file, but for now, this file can be a simple text file containing something as simple as one line "Yea!  this is text from my first web page." Here's my index.html file:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>Increa Micro_httpd Homepage</title>
<meta content="Author" name="author"></head>
<body>Hello.&nbsp; The Micro_httpd server is working.<br>
<a href="files">Additional files</a>.<br>

Using Finder, click on the index.html file and make sure your index.html file properly shows up in the normal web browser you have.


Download micro_httpd and put the tarzip file into your home directory.  Double click the zip file to unzip it, and using Finder, click into the new micro_httpd directory.  Open a terminal window and type "cd ", and then drag the folder at the top of the Finder window into the terminal window.  The rest of the cd command will be populated with your directory location.  Press return.

Once in the micro_httpd directory, enter the command "make".  This will compile the C program using the gcc compiler installed on your MacBook Pro.  You may wish to change a few lines in the source code. This what prints up on the bottom of error pages.  Here are the two lines I changed in the source code:

#define SERVER_NAME "return to Micro_httpd root"
#define SERVER_URL ""

At the command prompt, type "./micro_httpd" and the program should run, kicking out about 13 lines of html text with a 500 Internal Error.  The error has to do with the fact that you specified no web page, so it's okay.  Get the compiled program to work before going further.

Now try accessing your web page using micro_httpd.  Still in the command window in your source code directory , type "./micro_httpd ~/public_html/".  The terminal window should print nothing when you press return.  Then, if you press another return, you should get a 400 Bad Request error (not the 500 Internal Error).


Next you need to hook up the Apple launchd program to run your web agent program each time an http request comes in on port 80.  Traditionally inetd is a Linux program that allows a program to be executed based on events, such as queries from the internet. Apple's OS X 10.6 has replaced inetd with launchd. In this simple application, each time lanchd runs the program, it will handle only one http query and then quit.  This is unlike a real web server which would stay active in memory and watch the inbound port by itself.

In your home directory, create the directory "~/Library/LaunchAgents/" if it doesn't exist and create an empty file with the command "touch ~/Library/LaunchAgents/com.myserver.micro_httpd.plist".  Then using Finder, double-click on the file and it should open with the plist editor.  This file is sort of like a Windows shortcut, or configuration file.  It will tell launchd where to find your program and how to run it.

Use the plist editor to create rows and make them look like the screenshot below, and save the file.  After you save the file, go back to the terminal window, and change the owner to root using the command "sudo chown root ~/Library/LaunchAgents/com.myserver.micro_httpd.plist"  Apple documentation says that plist files in your home directory need to have you as the owner, but I found this is not true.  Instead, they need to have root as the owner to propery run.  Remember, if you edit the file, change the owner back to yourself using the command "sudo chown {your-username} ~/Library/LaunchAgents/com.myserver.micro_httpd.plist.

plist example

Take a look at what other daemons and agents have been loaded with launchd.  Use the command "launchctl list".  Also, check to make sure nothing else is listening on the http port 80 using the command  "stroke 80 80"; it should print just one line confirming that it scanned, showing that port 80 did not respond.


Load your agent using the command "sudo launchctl load ~/Library/LaunchAgents/com.myserver.micro_httpd.plist".  If it says something about dubious ownership, you forgot to change the owner of the plist file to root.  Also, if you are using the Mac OS firewall, you should see a message pop up asking you if you want outside sources to be able to get through port 80.  Click on Allow.

allow access to port

You can now see if your agent loaded using the command "launchctl list | grep myserver". You should see one line print out with your sever label listed. 

You can see that port 80 is now active using the command "stroke 80 80", which should advise you that launchd is listening for TCP packets on port 80.  Whenever someone sends a web page request, launchd will run your micro_httpd program.  The program will do one reply and quit.

Go into the Apps, Utilities folder and run the Console App.  Check the Console Messages log file to be sure the launchd agent and your program are behaving (no repeated error messages over and over).

Load up your favorite web browswer and enter "" into the URL window.  You should see your index.html file rendered before your very eyes.

Once you think everything is working, use Finder to go back to the ~\micro_httpd directory and you should see a log file.  Click on the file to view it with the Console app, and be sure only the http connects are there, with no error messages. 

Known Issues

Any plist file you leave laying around in your LaunchAgents directory will load each time you log into your computer.  If you don't want it to load, you have to move the files out of that directory.  Or, each time you log in you could use the lauchctr program to unload it, but that would get tedious.

I haven't figured out one problem.  Although the agent is present upon reboot (check with the launchctl command), it is unresponsive (check with the stroke command or try to view it in the web browser).  The only solution I've found out is to use loadctl to reload it from the command line.  I think this might have something to do with the login sequence of events, but I haven't had time to figure it out.

Un-Install Instructions

You can unload your agent out of memory with the command "sudo launchd unload ~/Library/LaunchAgents/com.myserver.micro_httpd.plist".  Delete all the files and directories you created.

Additional Resources

Schedule Jobs Using launchd (Nathan Grigg)
OS X Man Pages for plist files (Mac Developer Library)
Creating Daemons and Agents (Mac Developer Library)
Launchd Example: Starting Web Server at Boot-time (Fitzgerald Steele)
Daemons and Agents (Mac Developer Library)

Valid HTML 4.01 Transitional

The skeleton of this document was originally created using AbiWord under a Gnome desktop.  It was subsequently edited by Konquerer to become the web page you are reading.  Created February 2013. Last updated Feb 2013.