mirror of
https://github.com/pragma-/pbot.git
synced 2024-11-06 03:59:31 +01:00
Update docs
This commit is contained in:
parent
097c657f0c
commit
d75cf1d0ad
@ -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)
|
||||
<!-- md-toc-end -->
|
||||
|
||||
## 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.
|
||||
|
@ -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)
|
||||
<!-- md-toc-end -->
|
||||
|
||||
## 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 <your 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)
|
||||
|
@ -2,7 +2,6 @@
|
||||
|
||||
## Table of Contents
|
||||
|
||||
|
||||
<!-- md-toc-begin -->
|
||||
* [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)
|
||||
<!-- md-toc-end -->
|
||||
<!-- md-toc-begin -->
|
||||
* [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)
|
||||
<!-- md-toc-end -->
|
||||
|
@ -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: <LOOPBACK,UP,LOWER_UP> 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: <BROADCAST,MULTICAST,UP,LOWER_UP> 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: <BROADCAST,MULTICAST,UP,LOWER_UP> 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
|
||||
|
1
doc/git-md-toc
Symbolic link
1
doc/git-md-toc
Symbolic link
@ -0,0 +1 @@
|
||||
../misc/git-md-toc
|
1
doc/makereadmetoc
Executable file
1
doc/makereadmetoc
Executable file
@ -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
|
1
doc/updatetocs
Executable file
1
doc/updatetocs
Executable file
@ -0,0 +1 @@
|
||||
./git-md-toc -u -m 2 *.md
|
Loading…
Reference in New Issue
Block a user