example-conf: revise the example servers: section

- Remove "8P#" as a sidrange default - it does not leave adequate room for larger networks
- Move the TS6 example to near the end; it has less demand than Unreal and P10
- Consistently use "must" to describe P10 cloaking options, where any misconfiguration will lead to serious desyncs
- Bumped example autoconnect times from 5 to 10 seconds
- Add the 'netname' option to server blocks that previously didn't include it
- Comment out the 'channels' setting on each server example by default
- Various wording clarifications

example-conf.yml

@@ -132,7 +132,7 @@ servers:
         #bindhost: 1.2.3.4
 
         # The full network name, used by plugins.
-        netname: "InspIRCd Network"
+        netname: "Change this"
 
         # Hostname we will use to connect to the remote server
         hostname: "pylink.yournet.local"
@@ -155,7 +155,7 @@ servers:
         # configure channels per service using keys in the name of "<servicename>_channels"
         # Comment out or remove these keys if you don't want service bots# to join any channels by
         # default.
-        channels: ["#pylink"]
+        #channels: ["#pylink"]
         #pylink_channels: ["#services"]
         #automode_channels: ["#chat"]
 
@@ -165,7 +165,7 @@ servers:
 
         # Sets autoconnect delay - comment this out or set the value below 1 to
         # disable autoconnect entirely.
-        autoconnect: 5
+        autoconnect: 10
 
         # Optional autoconnect settings:
         # Defines whether we should multiply the autoconnect delay by a certain value every time
@@ -242,46 +242,15 @@ servers:
         # InspIRCd's default WHOIS formatting. This defaults to true for consistency with PyLink 1.x.
         #force_whois_extensions: true
 
-    ts6net:
+    unrealnet:
         ip: ::1
+        port: 8067
 
         # Determines whether IPv6 should be used for this connection. Should the ip:
         # above be a hostname instead of an IP, this will also affect whether A records
         # (no IPv6) or AAAA records (IPv6) will be used in resolving it.
         ipv6: yes
 
-        port: 7000
-        recvpass: "abcd"
-        sendpass: "abcd"
-        hostname: "pylink.example.com"
-        sid: "8PY"
-        netname: "some TS6 network"
-        sidrange: "8P#"
-
-        protocol: "ts6"
-        autoconnect: 5
-
-        # Note: /'s in nicks are automatically converted to |'s for TS6
-        # networks (charybdis, etc.), since they don't allow "/" in nicks.
-        #separator: "|"
-
-        ### The following options are specific to TS6 servers:
-        # Toggles owner (+y), admin (+a), and halfop (+h) support for
-        # shadowircd/elemental-ircd/chatircd. These default to off for the best compatibility.
-        #use_owner: false
-        #use_admin: false
-        #use_halfop: false
-
-        # Sets the IRCd (channel/user mode set) to target - currently supported values include
-        # 'chatircd', 'charybdis', and 'elemental' (elemental-ircd). This option defaults to
-        # 'charybdis' if not set, and replaces the "use_elemental_modes" option from PyLink 1.2
-        # and earlier.
-        #ircd: charybdis
-
-    unrealnet:
-        ip: 1.2.3.4
-        port: 8067
-
         # Received and sent passwords. For passwordless links using SSL fingerprints, simply set
         # these two fields to "*" and enable SSL with a cert and key file.
         recvpass: "coffee"
@@ -292,10 +261,10 @@ servers:
 
         hostname: "pylink.example.com"
         sid: "2PY"
-        netname: "This should match your UnrealIRCd config"
+        netname: "Network name: this should match your UnrealIRCd config"
         sidrange: "8##"
         protocol: "unreal"
-        autoconnect: 5
+        autoconnect: 10
 
         # You can also define network-specific nicks, idents, and hosts for any service
         # bot using the configuration options "servicename_nick", etc.
@@ -310,11 +279,15 @@ servers:
 
     nefarious:
         ip: somenet.ddns.local
-        #ipv6: false
         port: 45454
-        recvpass: "recv"
+
-        sendpass: "send"
+        # When the IP field is set to a hostname, this option determines whether IPv4 or IPv6 should
-        hostname: "pylink.midnight.vpn"
+        # be used for the connection.
+        #ipv6: false
+
+        recvpass: "PASS123"
+        sendpass: "PASS321"
+        hostname: "pylink.somenet.ddns.local"
 
         # For P10, the SID and SID range options correspond to P10 server numerics. The PyLink
         # "sid" should be the numeric of the main server, and "sidrange" should be a range of
@@ -323,10 +296,14 @@ servers:
         # may get conflicts.
         sid: 50
         sidrange: "100-150"
-        channels: ["#lounge"]
+        #channels: ["#lounge"]
         protocol: p10
-        autoconnect: 5
+        autoconnect: 10
-        netname: "Nefarious test server"
+        netname: "Change this"
+
+        # Configures the relay separator. Note: /'s in nicks are automatically translated to |
+        # for IRCds other than Unreal and InspIRCd, since they are not supported in nicks.
+        #separator: "|"
 
         ### The following options are specific to P10 servers:
         # Determines whether extended accounts should be used for this network.
@@ -334,8 +311,8 @@ servers:
         # For other P10 IRCds, this should be set to FALSE.
         use_extended_accounts: true
 
-        # Sets the IRCd type. The following options are supported here: 'nefarious', 'snircd', 'ircu', and
+        # Sets the IRCd type. The following options are supported here: 'nefarious', 'snircd', 'ircu',
-        # 'generic'. This defaults to 'nefarious'.
+        # and 'generic'. This defaults to 'nefarious'.
         # With this key set to 'nefarious', FAKE (external vHost changing) and SETHOST (host changing
         # for PyLink / relay clients) are enabled, along with a set of modes tailored to Nefarious.
 
@@ -347,16 +324,18 @@ servers:
 
         # With this key set to 'generic', neither of these host changing features are enabled
         # and a baseline RFC1459 mode set is used. This configuration is not officially supported.
-        # This option was previously named "p10_ircd" in PyLink 1.2, but that name is now deprecated.
+
+        # (This option was previously named "p10_ircd" in PyLink 1.2, and that option name is
+        #  deprecated as of 2.0).
         ircd: nefarious
 
         # Determines whether account-based cloaks should be used (someone.users.yournet.org
-        # format). This should match your IRCd configuration:
+        # format). This setting MUST match your IRCd configuration.
         # On Nefarious, ENABLE this if HOST_HIDING_STYLE is set to either 1 or 3.
         # On other P10 IRCds, ENABLE this if HOST_HIDING is set to TRUE.
         use_account_cloaks: false
 
-        # The cloak suffix to be used for account-based cloaks. This **MUST** match your
+        # The cloak suffix to be used for account-based cloaks. This MUST match your
         # IRCd configuration if use_account_cloaks is enabled.
         cloak_suffix: "users.yournet.org"
 
@@ -367,10 +346,10 @@ servers:
 
         # Determines whether account-based cloaks should be used for opers
         # (someone.opers.yournet.org format). If use_account_cloaks is disabled,
-        # this will have no effect. This setting should match your IRCd configuration.
+        # this will have no effect. This setting MUST match your IRCd configuration.
         use_oper_account_cloaks: false
 
-        # The cloak suffix to be used for IRCop account-based cloaks. This **MUST** match your
+        # The cloak suffix to be used for IRCop account-based cloaks. This MUST match your
         # IRCd configuration if use_oper_account_cloaks is enabled.
         oper_cloak_suffix: "staff.yournet.org"
 
@@ -379,17 +358,43 @@ servers:
         # ENABLE this if HOST_HIDING_STYLE is set to either 2 or 3.
         use_hashed_cloaks: false
 
+    ts6net:
+        ip: 1.2.3.4
+        port: 7000
+        recvpass: "abcd"
+        sendpass: "abcd"
+        hostname: "pylink.example.com"
+        sid: "8PY"
+        netname: "Your Network Name"
+        sidrange: "8##"
+
+        protocol: "ts6"
+        autoconnect: 10
+
+        ### The following options are specific to TS6 servers:
+        # Toggles owner (+y), admin (+a), and halfop (+h) support for
+        # shadowircd/elemental-ircd/chatircd. These default to off for the best compatibility.
+        #use_owner: false
+        #use_admin: false
+        #use_halfop: false
+
+        # Sets the IRCd (channel/user mode set) to target - currently supported values include
+        # 'chatircd', 'charybdis', and 'elemental' (elemental-ircd). This option defaults to
+        # 'charybdis' if not set, and replaces the "use_elemental_modes" option from PyLink 1.2
+        # and earlier.
+        #ircd: charybdis
+
     # Sample Clientbot configuration, if you want to connect PyLink as a bot to relay somewhere
     # (or do other bot things).
     magicnet:
         ip: 1.2.3.4
         port: 6697
 
-        # Server password (optional). Some networks also forward this to NickServ, so you can
+        # Optional server password.
-        # use it to log in on connect.
         #sendpass: "wastedbytes103"
 
-        channels: ["#this-works-as-usual"]
+        netname: "Change this"
+        #channels: ["#this-works-as-usual"]
         protocol: "clientbot"
 
         # Once again, you can override the nick and ident of service bots on specific networks using
@@ -437,11 +442,11 @@ servers:
         # If this option is enabled, the bot will attempt SASL authentication even after it's
         # connected, as services become available throughout netsplits and reconnects.
         # Note: This requires an IRC server capable of IRCv3.2 cap-notify and sasl:
-        # InspIRCd 3.x and charybdis 4+ (and derivatives) are some compatible examples (as of 2016-12-19)
+        # InspIRCd 3.x and charybdis 4+ are some compatible IRCds as of 2016-12-19.
         #sasl_reauth: true
 
         # Raw IRC messages to send on connect. As of 2.0-alpha2, expansions such as $nick, $ident,
-        # and $host are also supported via Python template strings
+        # and $host are also supported via Python template strings:
         # (https://docs.python.org/3/library/string.html#template-strings)
         #autoperform:
         #   - "MODE $nick +B"