README

   1 # Requirements
   2 A gemini server with SCGI capabilities.
   3 This includes at least molly-brown, GLV-1.12556, gemserv, and stargazer.
   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 subsequent request with the same
  28 client 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 # Communication with child processes
  44 By default, gemrepl relies on (configurable) timeouts to determine when the
  45 child has stopped writing and is waiting for input. Alternatively,
  46 the child can write to file descriptor 3 to indicate when it is expecting
  47 input. To do this, it should write '<' to 3 whenever it is about to read a
  48 single line from stdin, and '>' once it has finished reading. This method
  49 leads to perfect synchronisation as long as the child never pauses long enough
  50 to trigger a timeout.
  51
  52 By default, the output of the process is presented unquoted as text/gemini.
  53 See the --format option for other possibilities.
  54
  55 # Environment variables
  56 The spawned command will be passed the sha256 hex-encoded hash of the client
  57 certificate in the environment variable TLS_CLIENT_HASH.
  58
  59 More precisely, this is the behaviour with molly-brown and GLV-1.12556;
  60 in general the value of the variable will be what the server sends as
  61 TLS_CLIENT_HASH with any prefix "SHA256:" stripped.
  62
  63 SPAWN_PARAMETER will be set to the query, if any, of the request which
  64 initially spawned the command.
  65
  66 # Permissions
  67 The socket file will be created, after first unlinking any existing file at
  68 the given path. The gemini server must have read-write access to the socket
  69 file. For safety, you may want to run the gemrepl process and the server as a
  70 different users. One way to achieve this is to have both users part of a
  71 common group, then run gemrepl as that group (e.g. using sg) with umask 0007.
  72 Example:
  73 ```
  74 sg gemini "umask 0007; gemrepl -s /tmp/test_socket cat"
  75 ```