ksgi

1
<article data-sblg-article="1" data-sblg-tags="tutorial" itemscope="itemscope" itemtype="http://schema.org/BlogPosting">
2
	<header>
3
		<h2 itemprop="name">
4
			FastCGI Deployments
5
		</h2>
6
		<address itemprop="author"><a href="https://kristaps.bsd.lv">Kristaps Dzonsons</a></address>
7
		<time itemprop="datePublished" datetime="2015-08-05">5 August, 2015</time>
8
	</header>
9
	<p>
10
		<aside itemprop="about">
11
			FastCGI allows for much higher throughput by running web applications as daemons.
12
			In this tutorial, I'll describe how to deploy a simple FastCGI application using <a href="kfcgi.8.html">kfcgi(8)</a>.
13
		</aside>
14
	</p>
15
	<p>
16
		The target system will be OpenBSD.
17
		Our FastCGI script will be deployed using the socket interface, which is the default on OpenBSD and supported on other web
18
		servers, such as Apache, as well.
19
		In this method, the FastCGI application creates a socket that listens for connections.
20
		The web server maps a web page to a socket, then connects to the socket and transmits requests.
21
	</p>
22
	<h3>
23
		Source Code
24
	</h3>
25
	<p>
26
		Let's start with the server itself.
27
		This will be brutally simple: it will respond to all requests and simply print <q>Hello, World</q> and nothing more.
28
		The difference between this and the usual CGI method is that all processing occurs in a loop instead of as the entire body of
29
		the program.
30
	</p>
31
	<figure class="sample">
32
		<pre class="prettyprint linenums">#include &lt;sys/types.h&gt; /* size_t, ssize_t */
33
#include &lt;stdarg.h&gt; /* va_list */
34
#include &lt;stddef.h&gt; /* NULL */
35
#include &lt;stdint.h&gt; /* int64_t */
36
#include &lt;kcgi.h&gt;
37

38
int
39
main(void)
40
{
41
  struct kreq req;
42
  struct kfcgi *fcgi;
43

44
  if (khttp_fcgi_init
45
     (&amp;fcgi, NULL, 0, NULL, 0, 0) != KCGI_OK)
46
    return 0;
47

48
  while (khttp_fcgi_parse(fcgi, &amp;req) == KCGI_OK) {
49
    khttp_head(&amp;req, kresps[KRESP_STATUS], 
50
      "%s", khttps[KHTTP_200]);
51
    khttp_head(&amp;req, kresps[KRESP_CONTENT_TYPE], 
52
      "%s", kmimetypes[KMIME_TEXT_PLAIN]);
53
    khttp_body(&amp;req);
54
    khttp_puts(&amp;req, "Hello, world!\n");
55
    khttp_free(&amp;req);
56
  }
57

58
  khttp_fcgi_free(fcgi);
59
  return 0;
60
}</pre>
61
	</figure>
62
	<p>
63
		This example doesn't do any real error checking or content validation, so it's pretty easy to understand.
64
		Consult the <a href="khttp_fcgi_init.3.html">khttp_fcgi_init(3)</a>, <a href="khttp_fcgi_parse.3.html">khttp_fcgi_parse(3)</a>,
65
		and <a href="khttp_fcgi_free.3.html">khttp_fcgi_free(3)</a> manpages to see how these work properly.
66
		Next comes the more tricky part: deploying as a FastCGI application.
67
	</p>
68
	<h3>
69
		Compile and Link
70
	</h3>
71
	<p>
72
		Compiling and linking follow the same logic as in the <a href="tutorial0.html">Getting Started with CGI in C</a>.
73
		Since we're going to install our application in a file-system jail, we'll statically compile it.
74
		If your operating system doesn't support static linking, you won't be able to run your application with a file-system jail
75
		unless you copy over all libraries into the jail.
76
		(This is not covered by this tutorial.)
77
	</p>
78
	<figure class="sample">
79
		<pre class="prettyprint lang-sh linenums">% cc `pkg-config --cflags kcgi` -c -o tutorial2.o tutorial2.c
80
% cc -static -o tutorial2 tutorial2.o `pkg-config --libs kcgi`</pre>
81
	</figure>
82
	<h3>
83
		Install
84
	</h3>
85
	<p>
86
		Our installation process will look a great deal like that of <a href="tutorial0.html">Getting Started with CGI in C</a> except
87
		that we'll change our paths around a bit.
88
		First, let's configure the web server.
89
		I'll assume this is OpenBSD's <a href="https://man.openbsd.org/httpd.8">httpd(8)</a>.
90
		The file-format documentation is <a href="https://man.openbsd.org/httpd.conf.5">httpd.conf(5)</a>.
91
	</p>
92
	<figure class="sample">
93
		<pre class="prettyprint lang-sh linenums">server "me.local" {
94
  listen on * port 80
95
  location "/fcgi-bin/*" {
96
    fastcgi socket "/run/httpd.sock"
97
    root "/"
98
  }
99
}</pre>
100
	</figure>
101
	<p>
102
		This will cause CGI requests to <span class="file">/fcgi-bin</span> to be routed into the socket at <span
103
			class="file">/run/httpd.sock</span>, which is relative to the server root <span class="file">/var/www</span>.
104
		Let's first install our web application within the server root.
105
	</p>
106
	<figure class="sample">
107
		<pre class="prettyprint lang-sh linenums">% doas mkdir -p /var/www/fcgi-bin
108
% doas install -m 0555 tutorial2 /var/www/fcgi-bin</pre>
109
	</figure>
110
	<p>
111
		We must now set up the socket by executing our server.
112
		We do this by using the <a href="kfcgi.8.html">kfcgi(8)</a> utility, which will securely create the FastCGI socket, enact the
113
		file-system jail, then execute a pool of applications.
114
	</p>
115
	<figure class="sample">
116
		<pre class="prettyprint lang-sh linenums">% doas kfcgi -U www -u www -- /fcgi-bin/tutorial2</pre>
117
	</figure>
118
	<p>
119
		That's it!  
120
		At this point, the web application (running as user <q>www</q>) is executing under the <a href="kfcgi.8.html">kfcgi(8)</a>
121
		daemon within the file-system jail at <span class="file">/var/www</span>.
122
		It has created the socket in <span class="file">/var/www/run/httpd.sock</span> as user <q>www</q>.
123
		The web server will now be able to connect to this socket for its requests.
124
	</p>
125
</article>
126