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