CGI.md - geomyidae - A small C-based gopherd.
(HTM) git clone git://bitreich.org/geomyidae/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/geomyidae/
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
(DIR) LICENSE
---
CGI.md (4280B)
---
1 # Introduction to CGI
2
3 Geomyidae has support for running scripts on each request, which will
4 generate dynamic content.
5
6 There are three modes: standard cgi, dynamic cgi and http compatibility
7 mode. (»CGI« as name was just taken, because that's easier to compare
8 to the web.)
9
10
11 ## Permissions
12
13 The scripts are run using the permissions of geomyidae. It is advised to
14 use the -g and -u options of geomyidae.
15
16
17 ## Beforehand
18
19 In these examples C: is what the client sends and S: what the server is
20 sending.
21
22 ## Stdout/Stdin I/O of the Scripts
23
24 All scripts called below, in TLS or Non-TLS mode, will get full access of
25 the socket of the connection, with the socket bound to stdin and stdout.
26 Geomyidae does not check for any connection duration. This allows to
27 create long-lasting streaming services, like radio or TV stations.
28
29 ## Calling Convention
30
31 Geomyidae will call the script like this:
32
33 % $gopherroot/test.cgi $search $arguments $host $port $traversal
34 $selector
35
36 When it is a plain request, the arguments will have these values:
37
38 C: /test.cgi
39 -> $search = ""
40 -> $arguments = ""
41 -> $host = server host
42 -> $port = server port
43 -> $traversal = ""
44 -> $selector = "/test.cgi"
45
46 If the request is for a type 7 search element, then the entered string by
47 the user will be seen as following:
48
49 C: /test.cgi searchterm (There is a TAB in-between)
50 -> $search = »searchterm«
51 -> $arguments = ""
52 -> $host = server host
53 -> $port = server port
54 -> $traversal = ""
55 -> $selector = "/test.cgi\tsearchterm"
56
57 When you are trying to give your script some calling arguments, the syntax
58 is:
59
60 C: /test.cgi?hello
61 -> $search = ""
62 -> $arguments = "hello"
63 -> $host = server host
64 -> $port = server port
65 -> $traversal = ""
66 -> $selector = "/test.cgi?hello"
67
68 If both ways of input are combined, the variables are set as following:
69
70 C: /test.cgi?hello=world searchterm (Beware! A Tab!)
71 -> $search = "searchterm"
72 -> $arguments = "hello=world"
73 -> $host = server host
74 -> $port = server port
75 -> $traversal = ""
76 -> $selector = "/test.cgi?hello=world\tsearchterm"
77
78 ## REST Calling Convention
79
80 There is a special mode in geomyidae to imitate REST calling abilities.
81
82 When a user requests some non-existing path, geomyidae will start from
83 the base and go up the path directories, until it reaches the first not
84 existing directory.
85
86 C: /base/some/dir/that/does/not/exist?some-arguments searchterm
87 -> base exists
88 -> some exists
89 -> dir does not exist
90 -> search for index.cgi or index.dcgi in /base/some
91 -> if found, call index.cgi or index.dcgi as follows:
92 -> $search = "searchterm"
93 -> $arguments = "some-arguments"
94 -> $host = server host
95 -> $port = server port
96 -> $traversal = "/dir/that/does/not/exist"
97 -> $selector = "/base/some/dir/that/does/not/exist?some-arguments\tsearchterm"
98
99 ## Standard CGI
100
101 The file extension "cgi" switches to this mode, where the output of
102 the script is not interpreted at all by the server and the script needs
103 to send raw content.
104
105 % cat test.cgi
106 #!/bin/sh
107 echo "Hello my friend."
108 %
109
110 The client will receive:
111
112 S: Hello my friend.
113
114
115 ## Dynamic CGI
116
117 For using dynamic CGI, the file needs to end in "dcgi", which will
118 switch on the interpretation of the returned lines by the server. The
119 interpreted for- mat is the same as in the .gph files.
120
121 % cat test.dcgi
122 #!/bin/sh
123 echo "[1|Some link|/somewhere|server|port]"
124 %
125
126 Here geomyidae will interpret the .gph format and return the valid
127 gopher menu item.
128
129 S: 1Some link /somewhere gopher.r-36.net 70
130
131 ## HTTP Compatibility
132
133 In case someone sends some HTTP request to geomyidae and other cases,
134 geomyidae will do this:
135
136 C: GET /some/dir HTTP/1.1
137 -> /GET does exist and is executable
138 -> call GET as follows:
139 -> $search = ""
140 -> $arguments = ""
141 -> $host = server host
142 -> $port = server port
143 -> $traversal = ""
144 -> $selector = "GET /some/dir HTTP/1.1\r\n"
145 (full raw request by the client.)
146
147 This allows to serve HTTP next go gopher and get TLS for free. Other
148 HTTP-like protocols can be used over gopher in simple scripts, like the
149 icecast upload protocol.
150
151 ## Environment Variables
152
153 Please see the manpage geomyidae(8) for all variables and their content.
154 All states of the script execution environment and client request are
155 available.
156
157
158 Have fun!
159