|
|
CGI.md - geomyidae - A small C-based gopherd. |
|
|
 |
git clone git://bitreich.org/geomyidae/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/geomyidae/ (git://bitreich.org) |
|
|
 |
Log |
|
|
|
Files |
|
|
|
Refs |
|
|
|
Tags |
|
|
|
README |
|
|
|
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 |
|