gophi/docs/USAGE.md

# Gophor Arguments
```
gophor [args]
       -root               Server root directory
       -bind-addr          IP address to bind to
       -port               Port to listen on
       -fwd-port           Outward-facing port
       -hostname           Server hostname (FQDN)

       -sys-log            System log output location ['stdout', 'null', $filename]
       -acc-log            Access log output location ['stdout', 'null', $filename]

       -cache-monitor-freq File cache freshness monitor frequency
       -cache-size         File cache size
       -cache-file-max     Max cached file size (megabytes)

       -restrict-paths     Restrict paths as new-line separated list of regex statements
                           (see documenation below)
       -remap-requests     Remap requests as new-line separated list of remap statements
                           (see documenation below)

       -cgi-dir            CGI scripts directory (empty to disable)
       -max-cgi-time       Max CGI script execution time
       -safe-path          CGI environment safe PATH variable
       -http-compat-cgi    Enable HTTP compatibility for CGI scripts by stripping headers
       -http-prefix-buf    Buffer size used for stripping HTTP headers

       -user-dir           User subdir for personal server space

       -read-deadline      Connection read deadline (timeout)
       -write-deadline     Connection write deadline (timeout)

       -conn-read-buf      Connection read buffer size (bytes)
       -conn-write-buf     Connection write buffer size (bytes)
       -conn-read-max      Connection read max (bytes)

       -file-read-buf      File read buffer size (bytes)

       -version            Print version string

# Gopher Specific Arguments
       -page-width         Gopher page width

       -footer-text        Footer text (empty to disable)

       -subgopher-size-max Subgophermap size max (megabytes)

       -admin              Generated policy file admin email
       -description        Generated policy file server description
       -geolocation        Generated policy file server geolocation
```

# Path Restrictions Regex

Path restrictions are parsed as a new-line separated list of regex statements:

`/some/regex/statement.*`

Internally the regex statements are parsed as (show as Python code):

`/match_statement`

```Python
regex = "(?m)" + "/match_statement".removeprefix("/") + "$"
```

Entries are parsed, compiled, and so matched-against in order. They are matched against
relative paths so please bear this in mind if you have user directories enabled.

# Request Remapping Regex

Request remapping is parsed as a new-line separated list of remap statements of form:

`/regex/matched/against -> /regex/template`

Internally, the request remapping statements are parsed as (shown as Python code):

`/match_statement -> /template_statement`

```Python
# Where the match statement is compiled using
regex = "(?m)" + "/match_statement".removeprefix("/") + "$"

# And the template is stored as
template = "/template_statement".removeprefix("/")
```

e.g. scripts within cgi-bin to the root directory:

`/(?P<uri>[^/]+) -> /cgi-bin/$uri`

Entries are parsed, compiled, and so matched-against in order. They are matched against
relative paths so please bear this in mind if you have user directories enabled.

# User server spaces

When user server spaces are enabled, they are accessed via the following gopher URL:

`gopher://server.host:70/1/~user`

Where the username supplied will then look for a user folder under:

`/home/$user/$user_folder`

For example:

User directory = `public_gopher`

`gopher://server.host:70/1/~grufwub`

Will fetch from the filesystem:

`/home/grufwub/public_gopher`