From ce7f5886c1b0f063114c14b218a9e830aea44dd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Mon, 2 Mar 2020 09:18:58 -0500
Subject: [PATCH] split the znc docs in the existing tutorial and reference
sections
---
tsa/howto/irc.mdwn | 317 +++++++++++++++++++++++----------------------
1 file changed, 159 insertions(+), 158 deletions(-)
diff --git a/tsa/howto/irc.mdwn b/tsa/howto/irc.mdwn
index a14f8cf3..762e4191 100644
--- a/tsa/howto/irc.mdwn
+++ b/tsa/howto/irc.mdwn
@@ -14,6 +14,53 @@ Tor makes extensive use of IRC with multiple active channels on the
[OFTC network](https://www.oftc.net/). Our user-visible documentation is at [this wiki
page](https://trac.torproject.org/projects/tor/wiki/org/onboarding/IRC).
+## Using the ZNC IRC bouncer
+
+The last time this section was updated (or that someone remembered to update
+the date her) is: **28 Feb 2020**. The current ZNC admin is pastly. Find him on
+IRC or at pastly@torproject.org if you need help.
+
+You need:
+
+- your ZNC username. e.g. `jacob`. For simplicity, the ZNC admin should have
+ made sure this is the same as your IRC nick
+- your existing ZNC password. e.g. `VTGdtSgsQYgJ`
+- a new password
+
+### Changing your ZNC password
+
+If you know your existing one, you can do this yourself without the ZNC admin.
+
+Given the assumptions baked into the rest of this document, the correct URL to
+visit in a browser is `https://ircbouncer.torproject.org:2001/`.
+
+- log in with your ZNC username and password
+- click *Your Settings* in the right column menu
+- enter your password in the two boxes at the top of the page labeled
+ *Password* and *Confirm Password*
+- scroll all the way down and click *Save*
+
+Done. You will now need to remember this new password instead of the old one.
+
+### Connecting to ZNC from an IRC client
+
+Every IRC client is a little different. This section is going to tell you the
+information you need to know as opposed to exactly what you need to do with it.
+
+- For a nick, use your desired nick. The assumption in this document is
+ `jacob`. Leave alternate nicks blank, or if you must, add an increasing
+number of underscores to your desired nick for them: `jacob_`, `jacob__` ...
+- For the server or hostname, the assumption in this document is
+ `ircbouncer.torproject.org`.
+- Server port is 2001 based on the assumption blah blah blah
+- Use SSL/TLS
+- For a server password or simply password (**not a nickserv password**: that's
+ different and unnecessary) use `jacob/oftc:VTGdtSgsQYgJ`.
+
+That should be everything you need to know. If you have trouble, ask your ZNC
+admin for help or find someone who knows IRC. The ZNC admin is probably the
+better first stop.
+
# Howto
We do not operate the OFTC network. The public support channel for
@@ -36,116 +83,7 @@ The new IRC server has been setup with the `roles::ircbox` by weasel
machine. This role simply sets up the machine as a "shell server"
(`roles::shell`) and installs `irssi`.
-## SLA
-
-No specific SLA has been set for this service
-
-## Design
-
-Just a regular Debian server with users from LDAP.
-
-## Issues
-
-No specific project has been created to track issues.
-
-# Discussion
-
-This page was originally created to discuss the implementation of
-"bouncer" services for other staff. While many people run IRC clients
-on the server over an SSH connexion, this is inconvenient for people
-less familiar with the commandline.
-
-It was therefore suggested we evaluate other systems to allow users to
-have more "persistence" online without having to overcome the
-"commandline" hurdle.
-
-## Goals
-
-### Must have
-
- * user-friendly way to stay connected to IRC
-
-### Nice to have
-
- * web interface?
- * LDAP integration?
-
-### Non-Goals
-
- * replacing IRC (let's not go there please)
-
-## Approvals required
-
-Maybe checking with TPA before setting up a new service, if any.
-
-## Proposed Solution
-
-Not decided yet. Possible options:
-
- * status quo: "everyone for themselves" on the shell server, znc ran
- by pastly on their own infra
- * services admin: pastly runs the znc service for tpo people inside
- tpo infra
- * TPA runs znc bouncer
- * alternative clients (weechat, lounge, kiwiirc)
- * irccloud
-
-## Cost
-
-Staff. Existing hardware resources can be reused.
-
-## Alternatives considered
-
- * [irssi](https://irssi.org/) in some terminal multiplexer like [tmux](https://github.com/tmux/tmux) [screen](https://www.gnu.org/software/screen/)
- or [dtach](https://irssi.org/)
- * [weechat](https://weechat.org/) in the same or with another [interface](https://weechat.org/about/interfaces/) like
- [web (Glowbear)](https://www.glowing-bear.org/), [Android](https://github.com/ubergeek42/weechat-android) or [iOS](https://github.com/mhoran/weechatRN)
- * [lounge](https://thelounge.chat/) webchat (nodejs, not packaged in Debian)
- * [ZNC][], a [bouncer](http://en.wikipedia.org/wiki/BNC_%28software%29#IRC), currently ran by @pastly on their own
- infrastructure for some tpo people
- * a Matrix gateway like [Riot.IM](https://about.riot.im/)
- * [KiwiIRC](https://kiwiirc.com/), both a service and a web app we could run
-
-[ZNC]: https://wiki.znc.in/ZNC
-
-### Discarded alternatives
-
-Most other alternatives have been discarded because they do not work
-with IRC and we do not wish to move away from that platform just
-yet. Other projects (like [qwebirc](https://thelounge.chat/)) were discarded because they do
-not offer persistence.
-
-Free software projects:
-
- * [Briar](https://briarproject.org/) - tor-based offline-first messenger
- * [Jabber/XMPP](https://xmpp.org/) - just shutdown the service, never picked up
- * [Jitsi](https://jitsi.org/) - audio, video, text chat
- * [Mattermost](https://mattermost.com/) - opensource alternative to slack, not federated
- * [Retroshare](https://retroshare.cc/) - old, complex, not packaged
- * [Rocket.chat](https://rocket.chat/) - not federated
- * [Scuttlebutt](https://www.scuttlebutt.nz/) - not a great messaging experience
- * [Signal](https://signal.org/) - in use at Tor, but poor group chat capabilities
- * [Telegram](https://telegram.org/) - [doubts about security reliability](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=767418#42)
- * [Tox](https://tox.chat/) - DHT-based chat system
- * [Wire](https://wire.com/) - not packaged in Debian
- * [Zulip](https://zulipchat.com/) - "team chat", not federated
-
-Yes, that's an incredibly long list, and probably not exhaustive.
-
-Commercial services:
-
- * [IRCCloud](https://www.irccloud.com/) - bridges with IRC, [somewhat decent privacy
- policy](https://www.irccloud.com/privacy)
- * [Slack](https://slack.com/) - [poor privacy policy](https://www.salon.com/2018/03/22/slack-makes-an-odd-privacy-update-amid-unfolding-facebook-privacy-scandal/)
- * [Discord](https://discordapp.com/) - voice and chat app, mostly for gaming
- * [Hangouts](https://hangouts.google.com/) - Google service
- * [Whatsapp](https://www.whatsapp.com/) - tied to Facebook
- * [Skype](https://www.skype.com/en/) - Microsoft
- * [Keybase](https://alternativeto.net/software/keybase/) - OpenPGP-encrypted chat, proprietary server-side
-
-None of the commercial services interoperate with IRC unless otherwise noted.
-
-# Setting up ZNC
+## Installation: ZNC
This section documents how pastly set up ZNC on TPA infra. It was originally
written 20 Nov 2019 and the last time someone updated something and remembered
@@ -159,7 +97,7 @@ Assumptions
- The ZNC user is `ircbouncer`.
- The host is `chives`.
-## Goals
+### Goals
- ZNC bouncer maintaing persistent connections to irc.oftc.net for "Tor people"
(those with @torproject.org addresses is pastly's litmus test) and buffering
@@ -176,7 +114,7 @@ web-based configuration and IRC:
ircbouncer.torproject.org
- Securely via a Tor onion service on port 80 and 2000 at some onion address
-## Necessary software
+### Necessary software
- Debian 10 (Buster)
@@ -191,13 +129,13 @@ web-based configuration and IRC:
pastly@chives:~$ tor --version
Tor version 0.3.5.8.
-## Setup steps
+### Setup steps
-### Obtain necessary software
+#### Obtain necessary software
See previous section
-### Create a special user
+#### Create a special user
Ask your friendly neighborhood Tor sysadmin to do this for you. It needs its
own home directory and you need to be able to `sudo -u` to it. For example:
@@ -208,7 +146,7 @@ own home directory and you need to be able to `sudo -u` to it. For example:
But to do this you need ...
-### Create a sudo password for yourself
+#### Create a sudo password for yourself
If you don't have one already.
@@ -227,7 +165,7 @@ Email the resulting block of armored gpg output to changes@db.torproject.org.
[sudo] password for pastly on chives:
ircbouncer
-### Choose a FQDN and get a TLS certificate
+#### Choose a FQDN and get a TLS certificate
Ask your friendly neighborhood Tor sysadmin to do this for you. It could be
chives.torproject.org, but to make it easier for users, my Tor sysadmin chose
@@ -253,7 +191,7 @@ And the sysadmin made ircbouncer part of the ssl-cert group.
uid=1579(ircbouncer) gid=1579(ircbouncer) groups=1579(ircbouncer),116(ssl-cert)
-### Couple nice things
+#### Couple nice things
- Create a .bashrc for ircbouncer.
@@ -270,7 +208,7 @@ And the sysadmin made ircbouncer part of the ssl-cert group.
ircbouncer@chives:~$ id -u
1579
-### Create initial ZNC config
+#### Create initial ZNC config
If you're rerunning this section for some reason, consider deleting everything
and starting fresh to avoid any confusion. If this is your first time, then
@@ -330,7 +268,7 @@ decisions:
[ ** ]
[ ?? ] Launch ZNC now? (yes/no) [yes]: no
-### Create TLS cert that ZNC can read
+#### Create TLS cert that ZNC can read
There's probably a better way to do this or otherwise configure ZNC to read
straight from /etc/ssl for the TLS cert/key. But this is what I figured out.
@@ -369,7 +307,7 @@ Open ircbouncer's crontab with `crontab -e` and add the following line
@weekly /home/ircbouncer/bin/znc-ssl-copy.sh
-### Create ZNC system service
+#### Create ZNC system service
This is our first systemd user service thing, so we have to create the
appropriate directory structure. Then we create a very simple `znc.service`.
@@ -399,7 +337,7 @@ also start it now. Finally we verify it is loaded and actively running.
CGroup: /user.slice/user-1579.slice/user@1579.service/znc.service
└─23814 /usr/bin/znc --foreground
-### Access web interface
+#### Access web interface
The sysadmin hasn't opened any ports for us yet and we haven't configured ZNC
to use TLS yet. Luckily we can still access the web interface securely with a
@@ -416,7 +354,7 @@ from my laptop to chives over which it will forward all traffic to
So now I can visit in a browser on my laptop `http://127.0.0.1:2000` and gain
access to ZNC's web interface securely.
-### Add TLS listener for ZNC
+#### Add TLS listener for ZNC
Log in to the web interface using the username and password you created during
the initial ZNC config creation.
@@ -432,7 +370,7 @@ For listen ports, add:
Click *Add* and ZNC will open a TLS listener on 2001.
-### Make ZNC reachable without tricks
+#### Make ZNC reachable without tricks
- Ask your friendly neighborhood Tor sysadmin to allow inbound 2001 in the
firewall.
@@ -546,49 +484,112 @@ identifying
If there is no problem, the ZNC admin is done.
-# Using ZNC as a User
+## SLA
-The last time this section was updated (or that someone remembered to update
-the date her) is: **28 Feb 2020**. The current ZNC admin is pastly. Find him on
-IRC or at pastly@torproject.org if you need help.
+No specific SLA has been set for this service
-You need:
+## Design
-- your ZNC username. e.g. `jacob`. For simplicity, the ZNC admin should have
- made sure this is the same as your IRC nick
-- your existing ZNC password. e.g. `VTGdtSgsQYgJ`
-- a new password
+Just a regular Debian server with users from LDAP.
-## Changing your ZNC password
+## Issues
-If you know your existing one, you can do this yourself without the ZNC admin.
+No specific project has been created to track issues.
-Given the assumptions baked into the rest of this document, the correct URL to
-visit in a browser is `https://ircbouncer.torproject.org:2001/`.
+# Discussion
-- log in with your ZNC username and password
-- click *Your Settings* in the right column menu
-- enter your password in the two boxes at the top of the page labeled
- *Password* and *Confirm Password*
-- scroll all the way down and click *Save*
+This page was originally created to discuss the implementation of
+"bouncer" services for other staff. While many people run IRC clients
+on the server over an SSH connexion, this is inconvenient for people
+less familiar with the commandline.
-Done. You will now need to remember this new password instead of the old one.
+It was therefore suggested we evaluate other systems to allow users to
+have more "persistence" online without having to overcome the
+"commandline" hurdle.
-## Connecting to ZNC from an IRC client
+## Goals
-Every IRC client is a little different. This section is going to tell you the
-information you need to know as opposed to exactly what you need to do with it.
+### Must have
-- For a nick, use your desired nick. The assumption in this document is
- `jacob`. Leave alternate nicks blank, or if you must, add an increasing
-number of underscores to your desired nick for them: `jacob_`, `jacob__` ...
-- For the server or hostname, the assumption in this document is
- `ircbouncer.torproject.org`.
-- Server port is 2001 based on the assumption blah blah blah
-- Use SSL/TLS
-- For a server password or simply password (**not a nickserv password**: that's
- different and unnecessary) use `jacob/oftc:VTGdtSgsQYgJ`.
+ * user-friendly way to stay connected to IRC
+
+### Nice to have
+
+ * web interface?
+ * LDAP integration?
+
+### Non-Goals
+
+ * replacing IRC (let's not go there please)
+
+## Approvals required
+
+Maybe checking with TPA before setting up a new service, if any.
+
+## Proposed Solution
+
+Not decided yet. Possible options:
+
+ * status quo: "everyone for themselves" on the shell server, znc ran
+ by pastly on their own infra
+ * services admin: pastly runs the znc service for tpo people inside
+ tpo infra
+ * TPA runs znc bouncer
+ * alternative clients (weechat, lounge, kiwiirc)
+ * irccloud
+
+## Cost
+
+Staff. Existing hardware resources can be reused.
+
+## Alternatives considered
+
+ * [irssi](https://irssi.org/) in some terminal multiplexer like [tmux](https://github.com/tmux/tmux) [screen](https://www.gnu.org/software/screen/)
+ or [dtach](https://irssi.org/)
+ * [weechat](https://weechat.org/) in the same or with another [interface](https://weechat.org/about/interfaces/) like
+ [web (Glowbear)](https://www.glowing-bear.org/), [Android](https://github.com/ubergeek42/weechat-android) or [iOS](https://github.com/mhoran/weechatRN)
+ * [lounge](https://thelounge.chat/) webchat (nodejs, not packaged in Debian)
+ * [ZNC][], a [bouncer](http://en.wikipedia.org/wiki/BNC_%28software%29#IRC), currently ran by @pastly on their own
+ infrastructure for some tpo people
+ * a Matrix gateway like [Riot.IM](https://about.riot.im/)
+ * [KiwiIRC](https://kiwiirc.com/), both a service and a web app we could run
+
+[ZNC]: https://wiki.znc.in/ZNC
+
+### Discarded alternatives
+
+Most other alternatives have been discarded because they do not work
+with IRC and we do not wish to move away from that platform just
+yet. Other projects (like [qwebirc](https://thelounge.chat/)) were discarded because they do
+not offer persistence.
+
+Free software projects:
+
+ * [Briar](https://briarproject.org/) - tor-based offline-first messenger
+ * [Jabber/XMPP](https://xmpp.org/) - just shutdown the service, never picked up
+ * [Jitsi](https://jitsi.org/) - audio, video, text chat
+ * [Mattermost](https://mattermost.com/) - opensource alternative to slack, not federated
+ * [Retroshare](https://retroshare.cc/) - old, complex, not packaged
+ * [Rocket.chat](https://rocket.chat/) - not federated
+ * [Scuttlebutt](https://www.scuttlebutt.nz/) - not a great messaging experience
+ * [Signal](https://signal.org/) - in use at Tor, but poor group chat capabilities
+ * [Telegram](https://telegram.org/) - [doubts about security reliability](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=767418#42)
+ * [Tox](https://tox.chat/) - DHT-based chat system
+ * [Wire](https://wire.com/) - not packaged in Debian
+ * [Zulip](https://zulipchat.com/) - "team chat", not federated
+
+Yes, that's an incredibly long list, and probably not exhaustive.
+
+Commercial services:
+
+ * [IRCCloud](https://www.irccloud.com/) - bridges with IRC, [somewhat decent privacy
+ policy](https://www.irccloud.com/privacy)
+ * [Slack](https://slack.com/) - [poor privacy policy](https://www.salon.com/2018/03/22/slack-makes-an-odd-privacy-update-amid-unfolding-facebook-privacy-scandal/)
+ * [Discord](https://discordapp.com/) - voice and chat app, mostly for gaming
+ * [Hangouts](https://hangouts.google.com/) - Google service
+ * [Whatsapp](https://www.whatsapp.com/) - tied to Facebook
+ * [Skype](https://www.skype.com/en/) - Microsoft
+ * [Keybase](https://alternativeto.net/software/keybase/) - OpenPGP-encrypted chat, proprietary server-side
+
+None of the commercial services interoperate with IRC unless otherwise noted.
-That should be everything you need to know. If you have trouble, ask your ZNC
-admin for help or find someone who knows IRC. The ZNC admin is probably the
-better first stop.
--
GitLab