The webring is configured via a file in TOML format.
The rest of this document describes the format of the file and the settings it
can contain.
For the exact implementation, see the Config struct in src/config.rs.
In general, TOML files are made up of tables which contain key-value pairs. A key can have a table as its value, meaning tables can contain nested tables. Tables can be written in several ways. All of the following are equivalent in TOML:
-
[my-table] key = "value"
-
my-table = { key = "value" }
-
my-table.key = "value"
This flexibility allows you to specify options using whichever form you like.
To provide organization, the webring's settings are split into several tables. The settings are listed below, grouped into the tables they belong to. Tables for which no settings are specified can be omitted.
Some settings are required, and some are not. Some have defaults, and some do not. If a setting is not specified in the configuration file, the following happens:
| Required | Has default | Result |
|---|---|---|
| Yes | No | Error; webring will not start |
| Yes | Yes | Default value will be used |
| No | No | Setting is empty, i.e. has no value |
| No | Yes | Default value will be used |
This table contains settings pertaining to the webring server.
| Key | Required | Type | Default |
|---|---|---|---|
base-url |
no | string (URL) | https://ring.purduehackers.com |
static-dir |
yes | string (path) | /usr/share/webring/static |
Example:
[webring]
base-url = "https://ring.purduehackers.com"
static-dir = "static"Defines the URL of the webring itself. This is used mainly when checking members' sites to ensure they contain the correct links. The webring must know its own URL in order to know what the links to it should look like.
This URL must not be relative, i.e. it must have a valid authority (a.k.a.
"host" or "domain"). For example, file:///ring, while a valid URL, will be
rejected.
The directory from which static content will be served. Files in this directory
will be served with the path prefix /static. E.g. if the value of static-dir
is /www/ring, and the webring receives a request for /static/error.html, it
will serve /www/ring/error.html.
This directory also has a special purpose: the index.html file is a template
used to render the homepage, populated with the values of the ring's members.
See Homepage.md.
Note that this path is relative to the working directory in which the webring is run, not necessarily relative to the location of the configuration file. However, it is recommended to run the webring in the directory containing the configuration file, so that there is no confusion about relative paths.
Controls the capture and caching of site preview screenshots.
| Key | Required | Type | Default |
|---|---|---|---|
width |
no | integer (pixels) | 1280 |
height |
no | integer (pixels) | 808 |
settle-delay |
no | string (duration) | 1s |
cache-duration |
no | string (duration) | 6h |
Example:
[screenshots]
width = 1280
height = 808
settle-delay = "1s"
cache-duration = "1h15m"The viewport dimensions used for captured screenshots, in pixels. Generated fallback images use the same dimensions.
The amount of time to wait after a page loads before taking its screenshot. This gives asynchronously loaded assets time to render.
The amount of time a preview screenshot will be cached before being regenerated.
Settings pertaining to how the webring communicates over the network.
| Key | Required | Type | Default |
|---|---|---|---|
listen-addr |
no | string (ip:port) |
[::]:80 |
Specifies the address on which the webring will listen.
The value must be a string which can be parsed as a SocketAddr,
e.g. an IPv4 or IPv6 address followed by a colon and a port number. For more
details on the format, see here for IPv4 and here for IPv6.
You probably want to use the address 0.0.0.0 or [::], meaning listen on all
available IPv4 or IPv6 interfaces, respectively.
Controls the webring's logging behavior.
| Key | Required | Type | Default |
|---|---|---|---|
verbosity (alias level) |
no | string (one of off, trace, debug, info, warn, error) |
info for release builds; debug for debug builds |
log-file |
no | string (path) | none |
sentry-dsn |
no | string (URL) | none |
Example:
[logging]
level = "info"Sets the minimum severity to log. Messages with this severity or higher will be logged, and those with lower severity will be suppressed.
For example, at level info, messages at info, warn, and error will be
printed, and messages at trace and debug will not.
The value off means no messages will be printed; logging is disabled.
Specifies a path to a file to write logs to in addition to the standard error stream. New log lines will be appended to the file; the webring will never truncate the file. The file will be created if it does not exist.
When set, the Sentry integration will be enabled. This sets the DSN to send events to. See Sentry's documentation for more details.
Controls the Discord integration.
| Key | Required | Type | Default |
|---|---|---|---|
webhook-url |
no | string (URL) | none |
Sets the URL of the Discord webhook, which will be executed to send messages. This must be the full URL of an Execute Webhook API endpoint.
If set, members whose sites fail validation (and whose discord-id is set) will
be sent a message on Discord explaining the problem. The message is sent to
whichever server and channel the webhook is created for.
This table is a little different; instead of unique settings, it contains the list of the webring's members. Each key in this table is the name of a member, and the value is a table configuring the member's site. While all settings discussed so far apply to the webring as a whole, each member's table is unique to that member; the settings within do not apply to other members.
Member settings:
| Key | Required | Type | Default |
|---|---|---|---|
url |
yes | string (URL) | none |
discord-id |
no | integer | none |
check-level |
no | string (one of none/off, online/up, links/full) |
full |
Examples (all are equivalent):
-
[members.kian] url = "https://kasad.com" discord-id = 123 [members.henry] url = "https://hrovnyak.gitlab.io" check-level = "online"
-
[members] kian = { url = "https://kasad.com", discord-id = 123 } henry = { url = "https://hrovnyak.gitlab.io", check-level = "online" }
-
members.kian = { url = "https://kasad.com", discord-id = 123 } members.henry = { url = "https://hrovnyak.gitlab.io", check-level = "online" }
-
members.kian.url = "https://kasad.com" members.kian.discord-id = 123 members.henry.url = "https://hrovnyak.gitlab.io" members.henry.check-level = "online"
The URL of the member's site.
The member's Discord user ID. Note that this is not their username, but rather is a number. See this article for how to find someone's user ID.
If unset, this member will not be notified on Discord when their site fails checks.
See the discord table for more on the Discord integration.
The level of check to perform on this member's site. Checks are performed on every site before users are sent there. E.g. if the user requests the next site in the ring coming from A, and site B is not online, B will be silently skipped, and the user will be sent to the next passing site, e.g. C.
The options are:
-
offornone: No checks are performed. The site is considered to always be passing. -
uporonline: The site is considered to pass if it responds to HTTP requests with a successful (200-299) response. -
fullorlinks: The site must pass the previous check, and must also respond with an HTML body containing links (<a>elements) with the following destinations as their destination (hrefattribute):<RING_BASE_URL><RING_BASE_URL>/prevor<RING_BASE_URL>/previous(with optional?host=parameter)<RING_BASE_URL>/next(with optional?host=parameter)
If any of these links is missing, the site fails the check. Additionally, elements of any kind with a
data-phwebringattribute containing the valuehome,prev/previous, ornextwill be accepted instead of a link element.
If the configuration file is changed while the webring is running, this change
will be detected, and the webring will attempt to re-load the member list.
Only the members table is re-loaded; other changes will not be applied.
If the updated configuration file is invalid, an error will be logged and the update will be ignored, leaving the webring running the old configuration.