From 5503670a320f7e7d090110d4b2ae326e9f64e0c7 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Tue, 7 Feb 2017 15:45:03 -0500 Subject: rename README as markdown for better visibility --- README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..4528550 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ +KVM-Manager + +Authors: Daniel Kahn Gillmor + Jamie McClelland + Greg Lyle +Copyright © 2009-2011 +License: GPL-3+ + +This is a small set of scripts to make it relatively easy to manage a +stable of kvm instances in a fairly secure and isolated fashion. + +The basic model is to use runit to supervise each KVM instance, with a +single, non-privileged user account for each instance. You can login +via ssh as the non-privileged user and, via screen, access the +instance's console. + +Dependencies: + + runit : for system supervision + kvm : for the virtual machine emulator + socat : For communications with the monitor and console of guests + screen : for the detached, logged serial console + bridge-utils : for configuring a bridge device + lvm2 : for creating the relevant block devices + udev : for configuring the block devices with proper permissions + fakeroot : for rebuilding the initramfs as a regular user in di-maker + xorriso : for grub2 to make an iso in di-maker + genisoimage : for di-maker to work with an existing iso + sgabios : for early pre-bootloader (like ipxe) output + +Recommendations: + + openssh-server : i've been using ssh to access the vm's serial console + +INSTALLATION + + * Install dependencies: + + apt-get install runit kvm screen bridge-utils lvm2 udev socat sgabios + + If you want to be able to use di-maker, you'll also need: + + apt-get install fakeroot xorriso grub2 + + * Link programs into /usr/local/sbin: + + ln -s $(pwd)/{di-maker,kvm-manager,kvm-creator} /usr/local/sbin/ + + * Link screen configuration file into /etc + + ln -s $(pwd)/screenrc.kvm-manager /etc/ + + * Configure your host network to use a bridge. If your network adaptor + is eth0, you can use the following in /etc/network/interfaces + + auto br0 + iface br0 inet static + [Put your normal IP config for eth0 here...] + hwaddress ether xx:yy:zz:aa:bb:cc + bridge_ports eth0 + + Note: explicitly setting the hwaddress of your bridge to the same + MAC address as your existing NIC ("ip link show eth0 | grep ether") + is a good idea -- it seems to avoid periods of network connectivity + outages for the host when new interfaces get added to or removed + from the bridge. + + * Alternately, you can create an internal-only bridge, and tell your + host to pass traffic to it: + + auto br0 + iface br0 inet static + [ internal IP address information ] + post-up echo 1 > /proc/sys/net/ipv4/conf/br0/forwarding + +INSTALLING DEBIAN ONTO YOUR VIRTUAL SERVER + +To create a KVM instance, run: + + kvm-creator create $GUESTNAME [ $VG [$DISKSIZE [$RAM] ] ] + +You can replace "create" with "demo" to see the default values for non- +specified options. + +The creator scripts creates a username and home directory, logical volume, and +the required directory in /etc/sv/kvm/GUESTNAME from which the kvm-manager +script is run. After creating your virtual server, you can modify the files in +/etc/sv/kvm/GUESTNAME/env to change initial settings. + +You may also add ssh key's to /home/GUESTNAME/.ssh/authorized_keys to provide +additional access to other users. + +At this point, your virtual server is created, however, it has no operating system +and it has not been started. + +There are two options for installing debian onto the virtual server: + + * netboot + * iso (like a CD install) + +To use netboot, make sure you have a working DHCP server running on your +host server and offering addresses over your bridge interface. + +Then, indicate that the server should boot via the network with: + + touch /home/$GUESTNAME/vms/$GUESTNAME/netboot + +Alternatively, you can make a debian boot ISO image: + + * Make the directory /usr/local/share/ISOs + * Create a serial console enabled debian installer. + * cd /usr/local/share/ISOs + * di-maker d-i.iso + +Indicate that the server should boot via the CDROM (the equivelant of putting +the installer CD in the drive) with: + + ln -s /usr/local/share/ISOs/d-i.iso /home/$GUESTNAME/vms/$GUESTNAME/cd.iso + +STARTING YOUR VIRTUAL SERVER + + update-service --add /etc/sv/kvm/$GUESTNAME + +This process adds your virtual server to the runit service directory. + +If /home/$GUESTNAME/vms/$GUESTNAME/cd.iso exists, the server will behave as if you +set the CDROM as the boot device in the bios. + +If /home/$GUESTNAME/vms/$GUESTNAME/netboot exists, the server will behave as if you +set the network device as the boot device in the bios. + +After you have installed your server, be sure to delete these files if they exist or +your server won't boot properly. + +ACCESSING YOUR VIRTUAL SERVER + +To access the guest's serial console, do: + + ssh -t $GUESTNAME@host.machine screen -x $GUESTNAME + +To access the guest's KVM monitor, do: + + ssh -t $GUESTNAME@host.machine socat vms/$GUESTNAME/monitor.socket STDIO + +HACKING + +All patches, fixes, suggestions welcome! -- cgit v1.2.3