README

   1 # Requirements
   2 A gemini server with SCGI capabilities.
   3 This includes at least molly-brown, GLV-1.12556, and gemserv.
   4
   5 # Building
   6 ```
   7 make
   8 ```
   9
  10 # Basic usage
  11 Configure your server to use SCGI with a given socket path,
  12 e.g. in molly-brown config add something like:
  13 ```
  14 [SCGIPaths]
  15 "/gemrepl" = "/tmp/gemrepl_socket"
  16 ```
  17
  18 Then run gemrepl as
  19 ```
  20 gemrepl -s /tmp/gemrepl_socket COMMAND ARGS
  21 ```
  22 (you may want to try with 'cat' as the command while testing your setup).
  23 For simplicity, you can run gemrepl as the same user as the server; see
  24 Permissions below for a better approach.
  25
  26 When a user requests "/gemrepl" and presents a client certificate, an instance
  27 of the command will be spawned. On each request with the same client
  28 certificate, the query (if any) will be written to the process, and any
  29 (timely) output of the process will be given in the response.
  30
  31 See the examples/ directory for ideas of how this could be used.
  32
  33 # Security
  34 Perhaps it should go without saying, but be careful with this! You are
  35 allowing arbitrary internet users to run COMMAND on your machine and to write
  36 arbitrary input to it. Be sure that they can't get a shell this way!
  37
  38 You should also worry about DoS. A limited number of subprocesses will be
  39 spawned, after which the longest-idle process will be killed to allow a new
  40 one to be spawned. If COMMAND is going to consume significant resources, you
  41 may wish to use the --max-children option to reduce this maximum.
  42
  43 # Options
  44 The --read-timeout and --pause-timeout options control timeouts; after writing
  45 any input to the child process, gemrepl will wait for read-timeout ms for the
  46 child to write something, and then will continue to read until it is silent
  47 for pause-timeout ms.
  48
  49 To shortcut these timeouts, the child can write (anything) to stderr to
  50 indicate that it has finished writing to stdout and is ready for more input.
  51
  52 By default, the output of the process is presented unquoted as text/gemini,
  53 and it is expected to use unix-style newlines. See the --format and
  54 --no-lf-crlf options for other possibilities.
  55
  56 # Environment variables
  57 The spawned command will be passed the sha256 hex-encoded hash of the client
  58 certificate in the environment variable TLS_CLIENT_HASH.
  59
  60 More precisely, this is the behaviour with molly-brown and GLV-1.12556;
  61 in general the value of the variable will be what the server sends as
  62 TLS_CLIENT_HASH with any prefix "SHA256:" stripped.
  63
  64 # Permissions
  65 The socket file will be created, after first unlinking any existing file at
  66 the given path. The gemini server must have read-write access to the socket
  67 file. For safety, you may want to run the gemrepl process and the server as a
  68 different users. One way to achieve this is to have both users part of a
  69 common group, then run gemrepl as that group (e.g. using sg) with umask 0007.
  70 Example:
  71 ```
  72 sg gemini "umask 0007; gemrepl -s /tmp/test_socket cat"
  73 ```