diff --git a/applets/pbot-vm/vagrant/README.md b/applets/pbot-vm/vagrant/README.md index 415033d3..5e0dd2d6 100644 --- a/applets/pbot-vm/vagrant/README.md +++ b/applets/pbot-vm/vagrant/README.md @@ -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: + + sh echo Hello world! + 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 -### (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 diff --git a/doc/README.md b/doc/README.md index 005a274b..1df81cfe 100644 --- a/doc/README.md +++ b/doc/README.md @@ -5,6 +5,7 @@ * [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 @@ * [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) * [Frequently Asked Questions](FAQ.md#frequently-asked-questions) diff --git a/doc/VirtualMachine.md b/doc/VirtualMachine.md index 53263d63..75cb536d 100644 --- a/doc/VirtualMachine.md +++ b/doc/VirtualMachine.md @@ -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