From d75cf1d0ad4e5f24feaff6d312f7828e3fe2c375 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Sun, 7 May 2023 13:22:37 -0700 Subject: [PATCH] Update docs --- doc/AntiAbuse.md | 13 ++++++ doc/FAQ.md | 3 ++ doc/README.md | 5 +- doc/VirtualMachine.md | 103 ++++++++++++++++++++++++++++++++++++------ doc/git-md-toc | 1 + doc/makereadmetoc | 1 + doc/updatetocs | 1 + 7 files changed, 112 insertions(+), 15 deletions(-) create mode 120000 doc/git-md-toc create mode 100755 doc/makereadmetoc create mode 100755 doc/updatetocs diff --git a/doc/AntiAbuse.md b/doc/AntiAbuse.md index 770d95eb..0222b1c9 100644 --- a/doc/AntiAbuse.md +++ b/doc/AntiAbuse.md @@ -11,6 +11,7 @@ PBot can monitor channels for abusive behavior and take appropriate action. * [Anti-away/Nick-control](#anti-awaynick-control) * [Anti-auto-rejoin control](#anti-auto-rejoin-control) * [Opping/Deopping](#oppingdeopping) +* [Setting up automatic join-flood enforcement](#setting-up-automatic-join-flood-enforcement) ## Flood control @@ -53,3 +54,15 @@ When such a case is detected, PBot will kickban the offender (with a kick messag ## Opping/Deopping ChanServ can op and deop PBot as necessary, unless the channel `permop` metadata is set to a true value. PBot will wait until about 5 minutes have elapsed before requesting a deop from ChanServ. This timeout can be controlled via the `general.deop_timeout` registry value, which can be overriden on a per-channel basis. +## Setting up automatic join-flood enforcement +PBot performs its join-flood enforcement in a separate channel to reduce noise in the main channel. + +Let's say you want to set up join-flood enforcement for channel `#bash`. Here are all of the steps required to do that. + +* Create and register the `#stop-join-flood` channel. This is where PBot will forward join-flooders. Give it a sensible title like "You have been forwarded here due to join-flooding. If your IRC client or network issues have been resolved, you may `/msg PBot unbanme` to remove the ban-forward." +* Create and register the `#bash-floodbans` channel. This is where PBot do the banning/unbanning. Give PBot channel OPs here. +* Set an extended-ban in `#bash`: `/mode #bash +b $j:#bash-floodbans$#stop-join-flood`. This will retrieve the bans from `#bash-floodbans` for use in `#bash`. +* Join PBot to both `#bash` and `#bash-floodbans` so it can monitor `#bash` and set/remove the bans in `#bash-floodbans`. +* Optionally, configure the `#bash.join_flood_threshold` and `#bash.join_flood_time_threshold` registry entries if the defaults are not desirable. + +When someone is banned for join-flooding, they will be forwarded to `#stop-join-flood`. That channel should have a sensible `/topic` and ChanServ `on-join` message that clearly explains the channel's purpose and how to /msg PBot to remove the join-flood ban. PBot's `unbanme` command can be used twice per day. Each time it is used, PBot will send the user a message explaining how many more uses they have that day and why their uses are limited. diff --git a/doc/FAQ.md b/doc/FAQ.md index 3f26cbb1..7a53e4a2 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -10,6 +10,7 @@ This is a work in progress. More questions coming soon! * [How do I change my password?](#how-do-i-change-my-password) * [How do I make PBot remember my `date` timezone?](#how-do-i-make-pbot-remember-my-date-timezone) * [How do I make PBot remember my `weather` location?](#how-do-i-make-pbot-remember-my-weather-location) +* [How do I set up automatic join-flood enforcement?](#how-do-i-set-up-automatic-join-flood-enforcement) ## When I type `!version` it say "new version available"? @@ -122,3 +123,5 @@ create a user account for you if one does not exist. my location +## How do I set up automatic join-flood enforcement? +[See how to set up automatic join-flood enforcement here.(AntiAbuse.md#setting-up-automatic-join-flood-enforcement) diff --git a/doc/README.md b/doc/README.md index 06cf37cb..0f1f57a1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -2,7 +2,6 @@ ## Table of Contents - * [QuickStart](QuickStart.md#quickstart) * [Installation](QuickStart.md#installation) @@ -315,6 +314,7 @@ * [Anti-away/Nick-control](AntiAbuse.md#anti-awaynick-control) * [Anti-auto-rejoin control](AntiAbuse.md#anti-auto-rejoin-control) * [Opping/Deopping](AntiAbuse.md#oppingdeopping) + * [Setting up automatic join-flood enforcement](AntiAbuse.md#setting-up-automatic-join-flood-enforcement) * [Virtual Machine](VirtualMachine.md#virtual-machine) @@ -327,6 +327,8 @@ * [Add libvirt group to your user](VirtualMachine.md#add-libvirt-group-to-your-user) * [Download Linux ISO](VirtualMachine.md#download-linux-iso) * [Create a new virtual machine](VirtualMachine.md#create-a-new-virtual-machine) + * [libvirt](VirtualMachine.md#libvirt) + * [QEMU](VirtualMachine.md#qemu) * [Install Linux in the virtual machine](VirtualMachine.md#install-linux-in-the-virtual-machine) * [Set up serial ports](VirtualMachine.md#set-up-serial-ports) * [Set up virtio-vsock](VirtualMachine.md#set-up-virtio-vsock) @@ -351,4 +353,5 @@ * [How do I change my password?](FAQ.md#how-do-i-change-my-password) * [How do I make PBot remember my `date` timezone?](FAQ.md#how-do-i-make-pbot-remember-my-date-timezone) * [How do I make PBot remember my `weather` location?](FAQ.md#how-do-i-make-pbot-remember-my-weather-location) + * [How do I set up automatic join-flood enforcement?](FAQ.md#how-do-i-set-up-automatic-join-flood-enforcement) diff --git a/doc/VirtualMachine.md b/doc/VirtualMachine.md index e5724ead..7b36d412 100644 --- a/doc/VirtualMachine.md +++ b/doc/VirtualMachine.md @@ -3,13 +3,11 @@ PBot can interact with a virtual machine to safely execute arbitrary user-submitted system commands and code. -This document will guide you through installing and configuring a virtual machine -by using the widely available [libvirt](https://libvirt.org) project tools, such as -`virt-install`, `virsh`, `virt-manager`, `virt-viewer`, etc. - -If you're more comfortable working with QEMU directly instead, feel free to do that. -I hope this guide will answer everything you need to know to set that up. If not, -open an GitHub issue or /msg me on IRC. +This document will guide you through installing and configuring a Linux +virtual machine on a Linux host by using the widely available [libvirt](https://libvirt.org) +project tools, such as `virt-install`, `virsh`, and `virt-viewer`. Additionally, +if you'd prefer not to use libvirt, this guide will also demonstrate equivalent +Linux system commands and QEMU commands. Some quick terminology: @@ -37,6 +35,10 @@ PBOTVM_NOREVERT | not set | If set then the VM will not revert to previous snaps These steps need to be done only once during the first-time set-up. ### Prerequisites +For full hardware-supported virtualization at near native system speeds, we +need to ensure your system has enabled CPU Virtualization Technology and that +KVM is set up and loaded. + #### CPU Virtualization Technology Ensure CPU Virtualization Technology is enabled in your motherboard BIOS. @@ -56,7 +58,7 @@ If you see the above, everything's set up. Otherwise, consult your operating system manual or KVM manual to install and load KVM. #### libvirt and QEMU -Ensure libvirt and QEMU are installed and ready. +If using libvirt, ensure it is installed and ready. host$ virsh version --daemon Compiled against library: libvirt 7.6.0 @@ -65,8 +67,14 @@ Ensure libvirt and QEMU are installed and ready. Running hypervisor: QEMU 6.0.0 Running against daemon: 7.6.0 +Just QEMU (assuming x86_64): + + host$ qemu-system-x86_64 --version + QEMU emulator version 6.0.0 + Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers + If there's anything missing, please consult your operating system manual to -install the libvirt and QEMU packages. +install the libvirt and/or QEMU packages. On Ubuntu: `sudo apt install qemu-kvm libvirt-daemon-system` @@ -79,7 +87,8 @@ Add your user (or the `pbot-vm` user) to the `libvirt` group. host$ sudo adduser $USER libvirt -Log out and then log back in for the new group to take effect. +Log out and then log back in for the new group to take effect. Or use the +`newgrp` command. #### Download Linux ISO Download a preferred Linux ISO. For this guide, we'll use Fedora. Why? @@ -94,11 +103,21 @@ https://download.fedoraproject.org/pub/fedora/linux/releases/35/Server/x86_64/is is the Fedora Stable net-installer ISO used in this guide. ### Create a new virtual machine -To create a new virtual machine we'll use the `virt-install` command. +To create a new virtual machines, this guide offers two options. The first is +libvirt's `virt-install` command. It greatly simplifies configuration by +automatically creating networking bridges and setting up virtio devices. The +second options is manually using Linux system commands to configure network +bridges and execute QEMU with the correct options. + +#### libvirt +To create a new virtual machine we'll use the `virt-install` command. This +command takes care of setting up virtual networking bridges and virtual +hardware for us. If you prefer to manually set things up and use QEMU directly, +skip past the `virt-install` section. * First, ensure you are the `pbot-vm` user or that you have changed your current working directory to `pbot-vm`. The Linux ISO downloaded earlier should be present in this location. -Execute the following command: +If using libvirt, execute the following command: host$ virt-install --name=pbot-vm --disk=size=12,path=vm.qcow2 --cpu=host --os-variant=fedora34 --graphics=spice --video=virtio --location=Fedora-Server-netinst-x86_64-35-1.2.iso @@ -111,8 +130,64 @@ For further information about `virt-install`, read its manual page. While the ab give sufficient performance and compatability, there are a great many options worth investigating if you want to fine-tune your virtual machine. +#### QEMU +If you prefer not to use libvirt, we may need to manually create the network +bridge. Use the `ip link` command to list network interfaces: + + host$ sudo ip link + 1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + 2: eth0: mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 + link/ether 74:86:7a:4e:a1:95 brd ff:ff:ff:ff:ff:ff + altname enp1s0 + 3: virbr0: mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether 52:54:00:83:3f:59 brd ff:ff:ff:ff:ff:ff + inet 192.168.123.1/24 brd 192.168.123.255 scope global virbr0 + valid_lft forever preferred_lft forever + + +Create a new bridged named `pbot-br0`: + + host$ ip link add name pbot-br0 type bridge + host$ ip link set pbot-br0 up + +Add your network interface to the bridge: + + host$ ip link set eth0 master pbot-br0 + +Give the bridge an IP address (use an appropriate address for your network): + + host$ ip addr add dev pbot-br0 192.168.50.2/24 + +We will use the `qemu-bridge-helper` program from the `qemu-common` package to +create the TAP interface for us when we start the virtual machine and to remove +the interface when the virtual machine is shut-down. To set the program up, we +need to create its access control list file: + + host$ sudo mkdir /etc/qemu + host$ sudo chmod 755 /etc/qemu + host$ sudo echo allow pbot-br0 >> /etc/qemu/bridge.conf + host$ sudo chmod 640 /etc/qemu/bridge.conf + +To allow unprivileged users to create VMs using the network bridge, we must set +the SUID bit on the `qemu-bridge-helper` program: + + host$ chmod u+s /usr/lib/qemu/qemu-bridge-helper + +With the bridge configured, we move on to creating a sparse disk image for the +virtual machine: + + host$ qemu-img create -f qcow2 pbot-vm.qcow2 12G + +Then we can start QEMU (assuming x86_64) and tell it to boot the Fedora installer: + + host$ qemu-system-x86_64 -enable-kvm -cpu host -mem 1024 -hda pbot-vm.qcow2 -cdrom Fedora-Server-netinst-x86_64-35-1.2.iso -boot d -nic bridge,br=pbot-br0 -usb -device usb-tablet + +This command is the bare minimum for performant virtualization with networking. +See the QEMU documentation for interesting options to tweak your virtual machine. + #### Install Linux in the virtual machine -After executing the `virt-install` command above, you should now see a window +After executing the `virt-install` or `qemu` command above, you should now see a window showing Linux booting up and launching an installer. For this guide, we'll walk through the Fedora 35 installer. You can adapt these steps for your own distribution of choice. @@ -232,7 +307,7 @@ script. guest$ dnf install perl-interpreter perl-lib perl-IPC-Run perl-JSON-XS perl-English perl-IPC-Shareable -That installs the minium packages for the Perl interpreter (note we used `perl-interpreter` instead of `perl`), +This installs the minium packages for the Perl interpreter (note we used `perl-interpreter` instead of `perl`), as well as a few Perl modules. #### Install PBot VM Guest diff --git a/doc/git-md-toc b/doc/git-md-toc new file mode 120000 index 00000000..9c3d16cf --- /dev/null +++ b/doc/git-md-toc @@ -0,0 +1 @@ +../misc/git-md-toc \ No newline at end of file diff --git a/doc/makereadmetoc b/doc/makereadmetoc new file mode 100755 index 00000000..5a2f7d28 --- /dev/null +++ b/doc/makereadmetoc @@ -0,0 +1 @@ +./git-md-toc -x 4 -f QuickStart.md Plugins.md Commands.md Admin.md Factoids.md Registry.md Applets.md AntiAbuse.md VirtualMachine.md FAQ.md > toc && vi README.md diff --git a/doc/updatetocs b/doc/updatetocs new file mode 100755 index 00000000..1c5d6ca6 --- /dev/null +++ b/doc/updatetocs @@ -0,0 +1 @@ +./git-md-toc -u -m 2 *.md