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 Extensions for Management Control
5
		</h2>
6
		<address itemprop="author"><a href="https://kristaps.bsd.lv">Kristaps Dzonsons</a></address>
7
		<time itemprop="datePublished" datetime="2016-03-15">15 March, 2016</time>
8
	</header>
9
	<p>
10
		<aside itemprop="about">
11
			Subsequent version 0.8.1, <span class="nm">kcgi</span>'s FastCGI handling extends the <a
12
				href="http://www.fastcgi.com/devkit/doc/fcgi-spec.html">FastCGI specification</a> to allow the connection
13
			manager, <a href="kfcgi.8.html">kfcgi(8)</a>, to manage a variable-sized pool of <a href="kcgi.3.html">kcgi(3)</a>
14
			FastCGI workers.
15
		</aside>
16
	</p>
17
	<h3>
18
		Introduction
19
	</h3>
20
	<p>
21
		One significant weakness of FastCGI is that the application method (not the protocol) prohibits the worker manager from
22
		increasing the worker pool in response to load.
23
		The prohibition arises from section 3.2 of the specification, <a
24
			href="http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S3.2">Accepting Transport Connections</a>, which stipulates that
25
		workers must themselves accept incoming FastCGI connections on the transport socket.
26
	</p>
27
	<figure id="fig1">
28
		<img src="extending01-a.svg" alt="Accepting FastCGI Connections" />
29
		<figcaption>Relationship between web server, manager, and workers.</figcaption>
30
	</figure>
31
	<p>
32
		In the <a href="#fig1">figure</a>, the manager initiates the transport socket and starts its workers (steps 1&#8211;3).
33
		The workers then inherit the open transport socket and wait to accept transport connections.
34
		These are passed directly from the web server (steps 4&#8211;6).
35
		Unfortunately, if the transport socket backlog is filled, there is no way in the FastCGI specification for the manager to be
36
		appraised of the fact: no (known) systems supported by <span class="nm">kcgi</span> allow querying of the backlog size or being
37
		notified of backlog saturation.
38
		Since the manager is blind to anything but worker process status, the burden falls to the operator to pre-allocate workers.
39
	</p>
40
	<h3>
41
		Existing Solutions
42
	</h3>
43
	<p>
44
		The usual solution for this is to pre-allocate workers and simply fail on resource exhaustion: when the web server tries
45
		connecting to a saturated transport socket, it fails and the request is rejected by the web server.
46
		This is the method used by <a href="https://man.openbsd.org/httpd.8">httpd(8)</a> and other
47
		servers when using the <q>external process</q> mode.
48
		Obviously, this is sub-optimal.
49
		Many web servers address this by acting themselves as managers.
50
	</p>
51
	<figure id="fig2">
52
		<img src="extending01-b.svg" alt="Accepting FastCGI Connections" />
53
		<figcaption>Web server assuming the role of a manager.</figcaption>
54
	</figure>
55
	<p>
56
		In the <a href="#fig2">figure</a>'s configuration (which is standard in <a
57
			href="https://httpd.apache.org/mod_fcgid/">mod_fcgid</a> among other FastCGI implementations), the web server will start
58
		the transport socket and manage connections itself.
59
		Since it keeps track of worker activity by passing HTTP connections into the transport socket, it's able to allocate new workers
60
		on-demand.
61
	</p>
62
	<p>
63
		While this is an attractive solution, it puts a considerable burden of complexity on the web server to act both as an I/O broker
64
		and now a process manager as well.
65
		Moreover, the security model of the web server is compromised: since the FastCGI clients may need to run in the <q>root</q>
66
		file-system or without resource constraints, the web server must also run in this environment.
67
		This poses a considerable burden on the server developer: it must, to maintain separation of capabilities, manage connections in
68
		one process and manage connections in another, with a channel of communication between servers.
69
	</p>
70
	<h3>
71
		Potential Solutions
72
	</h3>
73
	<p>
74
		One method of solving this&#8212;and perhaps the best method&#8212;is for the worker manager to allocate a transport socket for
75
		each of its workers.
76
		It would then accept transport connections on behalf of the workers and then channel data to and from the workers' transport
77
		sockets and the main transport socket.
78
	</p>
79
	<figure id="fig3">
80
		<img src="extending01-c.svg" alt="Accepting FastCGI Connections" />
81
		<figcaption>Process manager multi-plexing transport sockets.</figcaption>
82
	</figure>
83
	<p>
84
		While an attractive fix, this puts a considerable burden on the transport manager to act both as a process manager and an I/O
85
		broker&#8212;the same problem in the <q>Existing Solutions</q> above, but for the manager instead of the server!
86
		Moreover, it puts considerable I/O overhead on the system for copying data: the manager will not be appraised of terminating
87
		transport connections unless it inspects the data itself.
88
		The result is that FastCGI responses cannot be spliced&#8212;it must be analysed.
89
	</p>
90
	<p>
91
		Another option is to provide each worker the ability to notify the manager of connection saturation.
92
		A saturated connection is one where accepting a socket happens instantly&#8212;this can be easily reckoned by making a
93
		non-blocking poll on the socket prior to accepting, and seeing if a connection is immediately available. 
94
		If so, then the connection is saturated at that moment and the manager might want to add more workers.
95
		Unfortunately, there is no trivial way for the worker to <q>talk back</q> to the manager: signals will be consolidated, so
96
		multiple <q>I'm saturated</q> signals will become one, and other means (such as shared memory) are increasingly complex.
97
	</p>
98
	<h3>
99
		Implemented Solution
100
	</h3>
101
	<p>
102
		The solution implemented by <span class="nm">kcgi</span> is very simple, but extends the language of the specification.
103
		In short, if the <code>FCGI_LISTENSOCK_DESCRIPTORS</code> environment variable is passed into the client, it will wait to
104
		receive a file descriptor (and a cookie) across the transport socket instead of accepting the descriptor itself.
105
		Then, when the connection is complete, the worker must respond with the cookie to the transport socket.
106
	</p>
107
	<figure id="fig4">
108
		<img src="extending01-d.svg" alt="Accepting FastCGI Connections" />
109
		<figcaption>Process manager passing file descriptors to workers.</figcaption>
110
	</figure>
111
	<p>
112
		In the <a href="#fig4">figure</a>, the manager listens on the transport socket and passes accepted descriptors directly to the
113
		workers, who then operate on the FastCGI data.
114
		This avoids the penalty (and complexity) of channeling I/O, but allows the manager to keep track of connections and allocate
115
		more workers, if necessary.
116
		This changes the current logic of <a href="http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S3.2">section 3.2</a> as follows:
117
	</p>
118
	<ol>
119
		<li>accept descriptor from the <code>FCGI_LISTENSOCK_FILENO</code> descriptor (standard input)</li>
120
		<li>operate on FastCGI data</li>
121
		<li>close descriptor</li>
122
	</ol>
123
	<p>
124
		To the following, noting the additional shut-down sequence that changes <a href="http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S3.5">section 3.5</a>.
125
	</p>
126
	<ol>
127
		<li>read descriptor and a 64-bit cookie from the <code>FCGI_LISTENSOCK_DESCRIPTORS</code> descriptor as specified in the environment</li>
128
		<li>operate on FastCGI data</li>
129
		<li>close descriptor</li>
130
		<li>write the 64-bit cookie value back to the <code>FCGI_LISTENSOCK_DESCRIPTORS</code> descriptor</li>
131
	</ol>
132
	<p>
133
		Applications implementing this can switch on whether the <code>FCGI_LISTENSOCK_DESCRIPTORS</code> value is a valid natural
134
		number to decide whether to use the existing or new functionality. 
135
	</p>
136
	<h3>
137
		Drawbacks
138
	</h3>
139
	<p>
140
		There are some minor draw-backs with this approach.
141
		First, it is not supported for operating systems that cannot pass file descriptors.
142
		Second, it stipulates depending upon an environment variable, which may be undesirable.
143
	</p>
144
	<p>
145
		Last, and most significantly, is that a manager wishing to use this feature can only do so with workers who are compiled to support the operation.
146
		In other words, there is no <q>fall-back</q> mechanism for the manager.
147
	</p>
148
</article>
149