mirror of
https://github.com/pragma-/pbot.git
synced 2025-11-04 00:27:23 +01:00
pbot-vm: documentation tweaks
This commit is contained in:
Pragmatic Software
parent
2547f035a1
commit
a3ab27dbac
@ -1,5 +1,10 @@
|
||||
# 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
vagrant halt
|
||||
@ -37,10 +68,13 @@ You may pass optional environment variables to override pbot-vm default configur
|
||||
vagrant box list
|
||||
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
|
||||
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>
|
||||
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
<!-- md-toc-begin -->
|
||||
* [QuickStart](QuickStart.md#quickstart)
|
||||
* [Installation](QuickStart.md#installation)
|
||||
* [Docker](QuickStart.md#docker)
|
||||
* [Installing Perl](QuickStart.md#installing-perl)
|
||||
* [Installing PBot](QuickStart.md#installing-pbot)
|
||||
* [git (recommended)](QuickStart.md#git-recommended)
|
||||
@ -319,31 +320,40 @@
|
||||
<!-- md-toc-end -->
|
||||
<!-- md-toc-begin -->
|
||||
* [Virtual Machine](VirtualMachine.md#virtual-machine)
|
||||
* [Initial virtual machine set-up](VirtualMachine.md#initial-virtual-machine-set-up)
|
||||
* [Prerequisites](VirtualMachine.md#prerequisites)
|
||||
* [CPU Virtualization Technology](VirtualMachine.md#cpu-virtualization-technology)
|
||||
* [KVM](VirtualMachine.md#kvm)
|
||||
* [libvirt and QEMU](VirtualMachine.md#libvirt-and-qemu)
|
||||
* [Make a pbot-vm user or directory](VirtualMachine.md#make-a-pbot-vm-user-or-directory)
|
||||
* [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)
|
||||
* [Reboot virtual machine](VirtualMachine.md#reboot-virtual-machine)
|
||||
* [Install software](VirtualMachine.md#install-software)
|
||||
* [Install Perl](VirtualMachine.md#install-perl)
|
||||
* [Install PBot VM Guest](VirtualMachine.md#install-pbot-vm-guest)
|
||||
* [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)
|
||||
* [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)
|
||||
* [Installation methods](VirtualMachine.md#installation-methods)
|
||||
* [libvirt and QEMU (recommended)](VirtualMachine.md#libvirt-and-qemu-recommended)
|
||||
* [Vagrant (experimental)](VirtualMachine.md#vagrant-experimental)
|
||||
* [Host vs guest](VirtualMachine.md#host-vs-guest)
|
||||
* [Environment variables](VirtualMachine.md#environment-variables)
|
||||
* [Initial virtual machine set-up](VirtualMachine.md#initial-virtual-machine-set-up)
|
||||
* [Prerequisites](VirtualMachine.md#prerequisites)
|
||||
* [CPU Virtualization Technology](VirtualMachine.md#cpu-virtualization-technology)
|
||||
* [KVM](VirtualMachine.md#kvm)
|
||||
* [libvirt and QEMU](VirtualMachine.md#libvirt-and-qemu)
|
||||
* [Make a pbot-vm user or directory](VirtualMachine.md#make-a-pbot-vm-user-or-directory)
|
||||
* [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)
|
||||
* [libvirt](VirtualMachine.md#libvirt-1)
|
||||
* [QEMU](VirtualMachine.md#qemu-1)
|
||||
* [Set up virtio-vsock](VirtualMachine.md#set-up-virtio-vsock)
|
||||
* [libvirt](VirtualMachine.md#libvirt-2)
|
||||
* [QEMU](VirtualMachine.md#qemu-2)
|
||||
* [Reboot virtual machine](VirtualMachine.md#reboot-virtual-machine)
|
||||
* [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-begin -->
|
||||
* [Frequently Asked Questions](FAQ.md#frequently-asked-questions)
|
||||
|
||||
@ -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
|
||||
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
|
||||
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`
|
||||
@ -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
|
||||
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
|
||||
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.
|
||||
to run any provisioning scripts from the [`./guest/provision`](../applets/pbot-vm/guest/provision) directory.
|
||||
|
||||
After running the `setup-guest` script, we need to make the environment changes take effect:
|
||||
|
||||
guest$ source /root/.bashrc
|
||||
|
||||
We no longer need the `/tmp/guest/` stuff. We can delete it:
|
||||
|
||||
guest$ rm -rf guest/
|
||||
### Install software
|
||||
If you received the message `!! No provisioning script available for $OS. Install packages manually. !!`,
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user