NOTE

This needs to be updated - a current example can be found at https://github.com/kristapsdz/kcgi-framework and more information on kcgi at https://kristaps.bsd.lv/kcgi/

BCHS Guide

This will be a quick-and-dirty guide to getting started with the BCHS stack. More information can be found at:

tilde.institute is set up to process all files with the .cgi extension via slowcgi(8). This allows for a multitude of possibilities - any compiled language can be used to develop web applications on an OpenBSD server. It's advised to use C because of the pledge(2) and unveil(2) system calls available, which allow for restricting privileges and restricted filesystem access, respectively.

Keep in mind that if you don't use the previously listed kcgi/ksql/kwebapp libraries, you will need to work with HTTP's eccentricities manually. For an example, here's the Hello World code from the LearnBCHS site. And here it is running as compiled CGI here at tilde.institute.

Once you've written your software to be served via CGI, be sure to statically link the executables. Sure, there's a larger file size, but the benefits outweigh that in this case - there's no relying on libraries I may or may not have available in the httpd chroot on tilde.institute. For example:

$ cc -static -g -W -Wall -o app.cgi app.c

When you've completed compilation, make sure to set permissions properly (755) and move it to the public folder in your home directory. httpd(8) is set to use index.html as the index file, however this can be changed to index.cgi or what-have-you by contacting the admins.

~institute user xvetrd has written a more detailed example on kcgi than is provided on the library's site. It includes an example makefile as well. The KCGI Starter archive is available here. Simply

curl -O https://tilde.institute/kcgi-starter.tar.gz

it to your home directory here on ~institute,

$ tar xzf kcgi-starter.tar.gz
$ cd kcgi-starter
$ make
$ make install

to test the compilation. It installs to ~/public_html with the proper ownership and permissions. View the index.c source and the makefile to see what goes on under the hood! Feel free to adapt it your own projects!

Note: You may need to add the following to CFLAGS

+I/usr/local/include

..and the following to LDFLAGS

-lkcgihtml -lkcgi -lz

back