GitHub/pbot
3
0
Fork 0
mirror of https://github.com/pragma-/pbot.git synced 2024-11-22 03:49:29 +01:00
Code Issues Projects Releases Wiki Activity

pbot-vm: documentation tweaks

Browse Source
This commit is contained in:
Pragmatic Software 2024-04-04 12:23:45 -07:00
parent 2547f035a1
commit a3ab27dbac
No known key found for this signature in database
GPG Key ID: CC916B6E3C84ECCE
3 changed files with 80 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
applets/pbot-vm/vagrant/README.md
View File

@ -1,5 +1,10 @@
# Vagrant instructions # Vagrant instructions
### Install libvirt and QEMU/KVM
Follow [PBot VM Prerequisites](../../../doc/VirtualMachine.md#prerequisites) up to the [libvirt and QEMU](../../../doc/VirtualMachine.md#libvirt-and-qemu)
section, then return to this guide.
### Install Vagrant ### Install Vagrant
To install vagrant on openSUSE, use: To install vagrant on openSUSE, use:
@ -16,14 +21,40 @@ If your distribution does not have a `vagrant-libvirt` package or if you need an
### Start Vagrant Box ### Start Vagrant Box
To start a virtual machine, `cd` into one of the PBot-VM Vagrant sub-directories and run: To start a virtual machine, `cd` into one of the PBot-VM Vagrant sub-directories and run the following command. This will download
the appropriate virtual machine image and automatically configure it as a PBot VM Guest.
vagrant up vagrant up
You may pass optional environment variables to override pbot-vm default configuration (see [Virtual Machine](../../../doc/VirtualMachine.md)): You may pass optional environment variables to override pbot-vm default configuration (see [PBot VM Environment Variables](../../../doc/VirtualMachine.md#environment-variables)):
PBOTVM_SERIAL=7777 PBOTVM_HEART=7778 vagrant up PBOTVM_SERIAL=7777 PBOTVM_HEART=7778 vagrant up
### Connect to Vagrant Box
vagrant ssh
### Start PBot VM Guest Server
sudo guest-server
Some distributions may require you to specify the full path:
sudo /usr/local/bin/guest-server
### Start PBot VM Host Server
After starting the guest-server, you must now start the host server.
../host/bin/vm-server
### Test PBot VM
In your instance of PBot, the `sh` and `cc`, etc, commands should now produce output:
<pragma-> sh echo Hello world!
<PBot> Hello world!
### Shutdown Vagrant Box ### Shutdown Vagrant Box
vagrant halt vagrant halt
@ -37,10 +68,13 @@ You may pass optional environment variables to override pbot-vm default configur
vagrant box list vagrant box list
vagrant box remove <name> vagrant box remove <name>
### (Optional) Install Alterantive Vagrant Box ### (Optional) Install Alternative Vagrant Box
To install an alternative Vagrant box with your preferred OS/distribution, search for one at https://app.vagrantup.com/boxes/search To install an alternative Vagrant box with your preferred OS/distribution, search for one at https://app.vagrantup.com/boxes/search
and then run the following command to download its Vagrantfile: and then make a new directory, e.g. FreeBSD-14, and copy one of the existing PBot-VM Vagrantfiles into
this directory, and then edit the `config.vm.box` line to point at the chosen OS/distribution, e.g. `freebsd/FreeBSD-14.0-CURRENT`.
Some boxes may have specific settings that you may need to copy over. To obtain and examine the box's Vagrantfile:
vagrant init <OS/distribution> vagrant init <OS/distribution>

60
doc/README.md
View File

@ -5,6 +5,7 @@
<!-- md-toc-begin --> <!-- md-toc-begin -->
* [QuickStart](QuickStart.md#quickstart) * [QuickStart](QuickStart.md#quickstart)
* [Installation](QuickStart.md#installation) * [Installation](QuickStart.md#installation)
* [Docker](QuickStart.md#docker)
* [Installing Perl](QuickStart.md#installing-perl) * [Installing Perl](QuickStart.md#installing-perl)
* [Installing PBot](QuickStart.md#installing-pbot) * [Installing PBot](QuickStart.md#installing-pbot)
* [git (recommended)](QuickStart.md#git-recommended) * [git (recommended)](QuickStart.md#git-recommended)
@ -319,31 +320,40 @@
<!-- md-toc-end --> <!-- md-toc-end -->
<!-- md-toc-begin --> <!-- md-toc-begin -->
* [Virtual Machine](VirtualMachine.md#virtual-machine) * [Virtual Machine](VirtualMachine.md#virtual-machine)
* [Initial virtual machine set-up](VirtualMachine.md#initial-virtual-machine-set-up) * [Installation methods](VirtualMachine.md#installation-methods)
* [Prerequisites](VirtualMachine.md#prerequisites) * [libvirt and QEMU (recommended)](VirtualMachine.md#libvirt-and-qemu-recommended)
* [CPU Virtualization Technology](VirtualMachine.md#cpu-virtualization-technology) * [Vagrant (experimental)](VirtualMachine.md#vagrant-experimental)
* [KVM](VirtualMachine.md#kvm) * [Host vs guest](VirtualMachine.md#host-vs-guest)
* [libvirt and QEMU](VirtualMachine.md#libvirt-and-qemu) * [Environment variables](VirtualMachine.md#environment-variables)
* [Make a pbot-vm user or directory](VirtualMachine.md#make-a-pbot-vm-user-or-directory) * [Initial virtual machine set-up](VirtualMachine.md#initial-virtual-machine-set-up)
* [Add libvirt group to your user](VirtualMachine.md#add-libvirt-group-to-your-user) * [Prerequisites](VirtualMachine.md#prerequisites)
* [Download Linux ISO](VirtualMachine.md#download-linux-iso) * [CPU Virtualization Technology](VirtualMachine.md#cpu-virtualization-technology)
* [Create a new virtual machine](VirtualMachine.md#create-a-new-virtual-machine) * [KVM](VirtualMachine.md#kvm)
* [libvirt](VirtualMachine.md#libvirt) * [libvirt and QEMU](VirtualMachine.md#libvirt-and-qemu)
* [QEMU](VirtualMachine.md#qemu) * [Make a pbot-vm user or directory](VirtualMachine.md#make-a-pbot-vm-user-or-directory)
* [Install Linux in the virtual machine](VirtualMachine.md#install-linux-in-the-virtual-machine) * [Add libvirt group to your user](VirtualMachine.md#add-libvirt-group-to-your-user)
* [Set up serial ports](VirtualMachine.md#set-up-serial-ports) * [Download Linux ISO](VirtualMachine.md#download-linux-iso)
* [Set up virtio-vsock](VirtualMachine.md#set-up-virtio-vsock) * [Create a new virtual machine](VirtualMachine.md#create-a-new-virtual-machine)
* [Reboot virtual machine](VirtualMachine.md#reboot-virtual-machine) * [libvirt](VirtualMachine.md#libvirt)
* [Install software](VirtualMachine.md#install-software) * [QEMU](VirtualMachine.md#qemu)
* [Install Perl](VirtualMachine.md#install-perl) * [Install Linux in the virtual machine](VirtualMachine.md#install-linux-in-the-virtual-machine)
* [Install PBot VM Guest](VirtualMachine.md#install-pbot-vm-guest) * [Set up serial ports](VirtualMachine.md#set-up-serial-ports)
* [Start PBot VM Guest](VirtualMachine.md#start-pbot-vm-guest) * [libvirt](VirtualMachine.md#libvirt-1)
* [Test PBot VM Guest](VirtualMachine.md#test-pbot-vm-guest) * [QEMU](VirtualMachine.md#qemu-1)
* [Save initial state](VirtualMachine.md#save-initial-state) * [Set up virtio-vsock](VirtualMachine.md#set-up-virtio-vsock)
* [Initial virtual machine set-up complete](VirtualMachine.md#initial-virtual-machine-set-up-complete) * [libvirt](VirtualMachine.md#libvirt-2)
* [Start PBot VM Host](VirtualMachine.md#start-pbot-vm-host) * [QEMU](VirtualMachine.md#qemu-2)
* [Test PBot](VirtualMachine.md#test-pbot) * [Reboot virtual machine](VirtualMachine.md#reboot-virtual-machine)
* [QEMU command from libvirt](VirtualMachine.md#qemu-command-from-libvirt) * [Install PBot VM Guest](VirtualMachine.md#install-pbot-vm-guest)
* [Install software](VirtualMachine.md#install-software)
* [Start PBot VM Guest](VirtualMachine.md#start-pbot-vm-guest)
* [Test PBot VM Guest](VirtualMachine.md#test-pbot-vm-guest)
* [Save initial state](VirtualMachine.md#save-initial-state)
* [Install host packages](VirtualMachine.md#install-host-packages)
* [Initial virtual machine set-up complete](VirtualMachine.md#initial-virtual-machine-set-up-complete)
* [Start PBot VM Host](VirtualMachine.md#start-pbot-vm-host)
* [Test PBot](VirtualMachine.md#test-pbot)
* [QEMU command from libvirt](VirtualMachine.md#qemu-command-from-libvirt)
<!-- md-toc-end --> <!-- md-toc-end -->
<!-- md-toc-begin --> <!-- md-toc-begin -->
* [Frequently Asked Questions](FAQ.md#frequently-asked-questions) * [Frequently Asked Questions](FAQ.md#frequently-asked-questions)

58
doc/VirtualMachine.md
View File

@ -393,50 +393,6 @@ The Tumbleweed installer will automatically reboot to a shell after the installa
as `root` and run `shutdown now -h`. Then run `virsh start pbot-vm`. (Using `shutdown now -r` to reboot as `root` and run `shutdown now -h`. Then run `virsh start pbot-vm`. (Using `shutdown now -r` to reboot
will not initialize the new serial/vsock devices.) Login as `root` when the virtual machine boots back up. will not initialize the new serial/vsock devices.) Login as `root` when the virtual machine boots back up.
### Install software
Now we can install any software and programming languages we want to make available
in the virtual machine. Use the `dnf search` or `zypper se` command or your distribution's documentation
to find packages. I will soon make available a script to install all package necessary for all
languages supported by PBot.
To make use of VM sockets, install the `socat` package:
Fedora:
guest$ dnf install socat
OpenSUSE Tumbleweed:
guest$ zypper in socat
For the C programming language you will need at least these:
Fedora:
guest$ dnf install libubsan libasan gdb gcc clang
OpenSUSE Tumbleweed:
guest$ zypper in libubsan1 libasan8 gdb gcc clang
Install packages for other languages as desired.
### Install Perl
Now we need to install Perl on the guest. This allows us to run the PBot VM Guest server
script.
Fedora:
guest$ dnf install perl-interpreter perl-lib perl-IPC-Run perl-JSON-XS perl-English perl-IPC-Shareable
OpenSUSE Tumbleweed:
guest$ zypper in perl-IPC-Run perl-JSON-XS make gcc
guest$ cpan i IPC::Shareable
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 ### Install PBot VM Guest
Next we install the PBot VM Guest server script that fosters communication between the virtual machine guest Next we install the PBot VM Guest server script that fosters communication between the virtual machine guest
and the physical host system. We'll do this inside the virtual machine guest system, logged on as `root` and the physical host system. We'll do this inside the virtual machine guest system, logged on as `root`
@ -456,17 +412,16 @@ Once that's done, run the following command:
This will install `guest-server` to `/usr/local/bin/`, set up some environment variables and This will install `guest-server` to `/usr/local/bin/`, set up some environment variables and
harden the guest system. Additionally, it'll autodetect your chosen OS/distribution and attempt harden the guest system. Additionally, it'll autodetect your chosen OS/distribution and attempt
to run any provisioning scripts from the `./guest/provision` directory. If no provisioning to run any provisioning scripts from the [`./guest/provision`](../applets/pbot-vm/guest/provision) directory.
scripts are available, it will warn you to manually install the packages for the `cc` languages
you want to use. You may use `./guest/provision/tumbleweed` as a reference.
After running the `setup-guest` script, we need to make the environment changes take effect: After running the `setup-guest` script, we need to make the environment changes take effect:
guest$ source /root/.bashrc guest$ source /root/.bashrc
We no longer need the `/tmp/guest/` stuff. We can delete it: ### Install software
If you received the message `!! No provisioning script available for $OS. Install packages manually. !!`,
guest$ rm -rf guest/ you must manually install any software and programming languages you want to make available
in the virtual machine. To do so, follow one of the [PBot VM provisioning scripts](../applets/pbot-vm/guest/provision/) as a guide.
### Start PBot VM Guest ### Start PBot VM Guest
We're ready to start the PBot VM Guest server. On the guest, as `root`, execute the command: We're ready to start the PBot VM Guest server. On the guest, as `root`, execute the command:
@ -478,7 +433,8 @@ this running.
### Test PBot VM Guest ### Test PBot VM Guest
Let's make sure everything's working up to this point. On the host, there should Let's make sure everything's working up to this point. On the host, there should
be two open TCP ports on `5555` and `5556`. On the host, execute the command: be two open TCP ports on `PBOTVM_SERIAL` and `PBOTVM_HEART` (default values `5555` and `5556`).
On the host, execute the command:
host$ nc -zv 127.0.0.1 5555-5556 host$ nc -zv 127.0.0.1 5555-5556