OpenBSD man pages

1 - Intro.md

Alternative restructuring to OpenBSD man pages

Brought to you by Boyz II Man:

https://soundcloud.com/openbsd-man-pages/boyz-ii-man-page-drone-prank-calls

Problem

Many newcomers to the OpenBSD project find the man pages hard to follow, and often report they had to resort to 3rd party books instead, in which they learned almost immediately due to their tendency to have a simple, non-technical language.

The OpenBSD Manual Revolution of 2020. Where tech talk and daily speech meet in the middle. Where newcomers feel more
invited, and where oldtimers have to spend less time answering basic questions.

Solution

• Don't start off man pages by jumping straight into the heavy stuff. Preface each man page with a short, dumbed down, misson statement type paragraph.
• Remove unnecessary reptitions of words or synonyms
• Avoid merging together different topics in the same paragraph
• Introduce an information architecture to the man pages where the lightest material go to the top and the heavier appear the longer down the page you go.

2 - NEW.md

RELAYD(8)                   System Manager's Manual                  RELAYD(8)

NAME
     relayd – relay daemon

SYNOPSIS
     relayd [-dnv] [-D macro=value] [-f file]

DESCRIPTION
     relayd is a load-balancer, application layer gateaway, and transparent
     proxy, allowing for simple setups of complex hosting environments,
     data transactions and internal networks.

     By comparing incoming connections and matching them up against the hosts
     and services configured in relayd.conf(5), it will relay data of you
     specified in this same file to its intended destination.

     There are currently two ways of relaying data; layer 3 and layer 7.

     Layer 3 happens at the packet level. Here, pf(4) joins in to better
     secure the flow of packets. This is disabled by default. To enable it,
     add this to the filter section of pf.conf(5):

           anchor "relayd/*"

     Layer 7 happens at the application level, and is taken care of by
     relayd itself.  This enables application level filtering and protocol-
     specific load-balancing. Under its hood, relayd is made up of
     relays, protocols, redirections, and tables.

     A relay represents a layer 7 load-balancing instance, each of which
     ends up listening to a TCP or UDP port.
         Protocols define which actions should be applied to data as it
     relays onto the next step.
         Redirections are layer 3 load-balancing instances, which similar
     to the ones in layer 3, also help aid the flow of packets.
         The last on the list is tables. Each table can store one or more
     hosts. If a table is already being used in layer 3, it will be mapped
    
     All the above are configurable properties of relayd.conf(5), while
     relayctl(8) gives direct real-time access to these.

3 - NEW.md

NAME
     relayd.conf – relay daemon configuration file

DESCRIPTION
     relayd.conf is the configuration file for the relay daemon, relayd(8).

     relayd.conf is divided into the following main sections:

     Macros
           User-defined variables may be defined and used later, simplifying
           the configuration file.

     Global Configuration
           Global settings for relayd(8).  Do note that the config file allows
           global settings to be added after defining tables in the config
           file, but those tables will use the built-in defaults instead of
           the global settings below them.

     Tables
           Table definitions describe a list of hosts, in a similar fashion to
           pf(4) tables.  They are used for relay, redirection, and router
           target selection with the described options and health checking on
           the host they contain.
dev@dev:~/.trash% man relayd
RELAYD(8)                   System Manager's Manual                  RELAYD(8)

NAME
     relayd – relay daemon

SYNOPSIS
     relayd [-dnv] [-D macro=value] [-f file]

DESCRIPTION
     relayd is a daemon to relay and dynamically redirect incoming connections
     to a target host.  Its main purposes are to run as a load-balancer,
     application layer gateway, or transparent proxy.  The daemon is able to
     monitor groups of hosts for availability, which is determined by checking
     for a specific service common to a host group.  When availability is
     confirmed, layer 3 and/or layer 7 forwarding services are set up by
     relayd.

     Layer 3 redirection happens at the packet level; to configure it, relayd
     communicates with pf(4).  To allow relayd to properly set up pf(4) rules,
     the following line is required in the filter section of pf.conf(5):

           anchor "relayd/*"

     Layer 7 relaying happens at the application level and is handled by
     relayd itself.  Various application level filtering and protocol-specific
     load-balancing options are available for relays.

     relayd works in terms of the following entities: relays, protocols,
     redirections, and tables.  A relay represents a layer 7 load-balancing
     instance.  Each instance translates to a listening TCP or UDP port.  A
     protocol defines which actions, if any, are taken on the packet payload
     as data crosses a relay.  A redirection represents a layer 3 load-
     balancing instance.  Each instance translates to a pf(4) rdr-to rule
     being added.  A table represents a group of hosts which can be checked
     for availability using the same method.  Each table contains at least one
     host.  If a table is used in a layer 3 load-balancing instance, it will
     be mapped to a pf(4) table containing only those hosts which are up.

     All these entities can be configured in relayd.conf(5), and relayctl(8)
     can be used to alter or report on the status of each entity.