commit eb4beef09633701791c66b609a2f5982e17cd901
parent bc165876cca3e084897953b302142f0122ce0a80
Author: Matt Brubeck <mbrubeck@limpet.net>
Date: Sat, 6 Feb 2021 01:56:07 -0800
Add source for Agate's Gemini capsule (#27)
Add source for Agate's Gemini capsule and update it for v2.4.0
Co-authored-by: mbrubeck <mbrubeck@limpet.net>
Diffstat:
| A | content/index.gmi | | | 179 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 179 insertions(+), 0 deletions(-)
diff --git a/content/index.gmi b/content/index.gmi
@@ -0,0 +1,179 @@
+# Agate
+
+## Simple Gemini server for static files
+
+Agate is a server for the [Gemini] network protocol, built with the [Rust] programming language. Agate has very few features, and can only serve static files. It uses async I/O, and should be quite efficient even when running on low-end hardware and serving many concurrent requests.
+
+Since Agate by default uses port 1965, you should be able to run other servers (like e.g. Apache or nginx) on the same device.
+
+## Learn more
+
+=> gemini://gemini.circumlunar.space/ Gemini project
+=> https://github.com/mbrubeck/agate Agate on GitHub
+=> https://crates.io/crates/agate Agate on crates.io
+
+## Installation and setup
+
+1. Download and unpack the pre-compiled binary:
+
+=> https://github.com/mbrubeck/agate/releases
+
+Or run `cargo install agate` to install agate from crates.io.
+
+Or download the source code and run `cargo build --release` inside the source repository, then find the binary at `target/release/agate`.
+
+2. Generate a self-signed TLS certificate and private key. For example, if you have OpenSSL 1.1 installed, you can use a command like the following. (Replace the hostname `example.com` with the address of your Gemini server.)
+
+```
+openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
+ -days 3650 -nodes -subj "/CN=example.com"
+```
+
+3. Run the server. You can use the following arguments to specify the locations of the content directory, certificate and key files, IP address and port to listen on, host name to expect in request URLs, and default language code(s) to include in the MIME type for for text/gemini files: (Again replace the hostname `example.com` with the address of your Gemini server.)
+
+```
+agate --content path/to/content/ \
+ --key key.rsa \
+ --cert cert.pem \
+ --addr :::1965 \
+ --addr 0.0.0.0:1965 \
+ --hostname example.com \
+ --lang en-US
+```
+
+All of the command-line arguments are optional. Run `agate --help` to see the default values used when arguments are omitted.
+
+When a client requests the URL `gemini://example.com/foo/bar`, Agate will respond with the file at `path/to/content/foo/bar`. If any segment of the requested path starts with a dot, agate will respond with a status code 52, wether the file exists or not (this behaviour can be disabled with `--serve-secret`). If there is a directory at that path, Agate will look for a file named `index.gmi` inside that directory.
+
+## Configuration
+
+### Directory listing
+
+You can enable a basic directory listing for a directory by putting a file called `.directory-listing-ok` in that directory. This does not have an effect on subdirectories.
+The directory listing will hide files and directories whose name starts with a dot (e.g. the `.directory-listing-ok` file itself or also the `.meta` configuration file).
+
+A file called `index.gmi` will always take precedence over a directory listing.
+
+### Meta-Presets
+
+You can put a file called `.meta` in a directory that stores some metadata about these files which Agate will use when serving these files. The file should be UTF-8 encoded. Like the `.directory-listing-ok` file, this file does not have an effect on subdirectories.
+Lines starting with a `#` are comments and will be ignored like empty lines. All other lines must start with a file name (not a path), followed by a colon and then the metadata.
+
+The metadata can take one of four possible forms:
+1. empty:
+ Agate will not send a default language parameter, even if it was specified on the command line.
+2. starting with a semicolon followed by MIME parameters:
+ Agate will append the specified string onto the MIME type, if the file is found.
+3. starting with a gemini status code (i.e. a digit 1-6 inclusive followed by another digit) and a space:
+ Agate will send the metadata wether the file exists or not. The file will not be sent or accessed.
+4. a MIME type, may include parameters:
+ Agate will use this MIME type instead of what it would guess, if the file is found.
+ The default language parameter will not be used, even if it was specified on the command line.
+
+If a line violates the format or looks like case 3, but is incorrect, it might be ignored. You should check your logs. Please know that this configuration file is first read when a file from the respective directory is accessed. So no log messages after startup does not mean the `.meta` file is okay.
+
+Such a configuration file might look like this:
+```text
+# This line will be ignored.
+index.gmi:;lang=en-UK
+LICENSE:text/plain;charset=UTF-8
+gone.gmi:52 This file is no longer here, sorry.
+```
+
+### Logging Verbosity
+
+Agate uses the `env_logger` crate and allows you to set the logging verbosity by setting the default `RUST_LOG` environment variable. For more information, please see the [documentation of `env_logger`].
+
+## Change log
+
+### 2.4.0
+
+* Added a sidecar file for specifying language, MIME media types or complete headers on a per file basis.
+* Improved logging output. This also uses the RUST_LOG environment variable now, so you can configure the log level.
+* Added some installation tools for Debian.
+
+There is a new maintainer: Johann150.
+
+### 2.3.0
+
+* Combine address and port in a single command-line parameter again.
+
+### 2.2.0
+
+* Split address and port into separate command-line parmeters.
+* Listen on both IPv4 and IPv6 interfaces by default.
+* Fix the logic for detecting hidden files.
+* Fix redirects of URLs with query strings.
+
+### 2.1.3
+
+* Send a TLS close-notify message when closing a connection.
+* Require absolute URLs in requests.
+* Switch to the Tokio async runtime.
+
+### 2.1.2
+
+* More complete percent-encoding of special characters in filenames.
+* Minor improvements to error logging.
+* Internal code cleanup.
+
+### 2.1.1
+
+* Handle percent-escaped paths in URLs.
+* Percent-escape whitespace characters in directory listings.
+* List directory contents in alphabetical order.
+
+### 2.1.0
+
+* Optional directory listing.
+* Updated dependencies.
+
+### 2.0.0
+
+* New format for command-line options. See the documentation or run `agate --help` for details.
+* Logging is enabled be default. Use the `--silent` flag to disable it.
+* New `--language` option to add a language tag to the MIME type for text/gemini responses.
+* Pre-compiled binaries are built with the `cross` tool, for better compatibility with older Linux systems.
+
+### 1.3.2
+
+* Updated dependencies.
+
+### 1.3.1
+
+* Updated dependencies.
+
+### 1.3.0
+
+* Verify hostname and port in request URL.
+* Improved logging.
+* Don't redirect to "/" when the path is empty.
+* Update dependencies.
+
+### 1.2.2
+
+* Use a faster/simpler library for guessing MIME types.
+* Update dependencies.
+* Publish pre-compiled ARM binaries.
+
+### 1.2.1
+
+* Reduce memory usage when serving large files.
+* Update dependencies.
+
+### 1.2.0
+
+* Change text/gemini filename extension from .gemini to .gmi.
+* Improve handling of requests that exceed 1KB.
+* Reduce memory allocations and speed up request parsing.
+* Update dependencies.
+
+### 1.1.0
+
+* Auto-detect MIME types.
+
+### 1.0.1
+
+* More accurate error codes.
+* Handle scheme-less URLs.
+* Throw error codes for unsupported URL types.
