From: hkclark Date: Fri, 2 Sep 2011 17:32:25 +0000 (-0400) Subject: Misc updates for VM X-Git-Tag: 5.9003~25^2~8 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=ec5b24b2e4c907cb9ea2a099ebf6fe69a9042cbd Misc updates for VM --- diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod index 2e214f0..fa3a360 100644 --- a/lib/Catalyst/Manual/Tutorial/01_Intro.pod +++ b/lib/Catalyst/Manual/Tutorial/01_Intro.pod @@ -182,6 +182,22 @@ L. =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE +The steps below briefly outline how you can download the Tutorial +Virtual Machine. This document uses the term "host machine" to refer to +the physical machine where you will run the virtualization software and +boot up the VM. The terms "guest machine" or just "VM" refer to the +virtual machine itself -- the thing where you actually do the tutorial +and that you boot up on the "host machine". + +Also, to reduce download size, the Tutorial VM just includes a minimal +command-line environment. In general, it is expected that people will +boot up the Tutorial VM on their main desktop (the "host machine" using +the terminology above) and then use that main desktop machine to SSH and +web browse into the "guest VM" as they work through the tutorial. If +you wish to install X-Windows (or any other packages), just use the +C (or C) Debian commands. + + =over 4 =item 1 @@ -217,47 +233,51 @@ Type "C" to get the IP address assigned to the virtual machine. You should get output along the lines of: eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69 - inet addr:192.168.245.128 Bcast:192.168.245.255 Mask:255.255.255.0 + inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0 ... You want the IP address on the second line below the C interface. The image it design to automatically use a DHCP-assigned address. -If DHCP is not working or is not available in your location, most -virtual machine "host" environments let's you select between one of -several different types of networking between the "guest" and the "host" -machine. - 1) Bridged - 2) NAT - 3) Local host only +Try to ping this IP address from your "host machine" (main desktop): -The Tutorial Virtual Machine defaults to "Bridged" -- this should result -in the VM acting like another device on your network that will get a -different DHCP IP address than the host machine. The advantage of this -approach, is that you can easily SSH and web browse to the guest virtual -machine. -In some environments, you might have better luck with "NAT" (Network -Address Translation) mode. With this configuration, the guest VM shares -the same IP address as the host machine. The downside of the approach -is that special configuration is required if you want to be able to SSH -or web browse to the guest VM (some virtual machine host environments -let you configure a "static NAT" or "port forwarding" to reach the guest -OS). + MainComputer:~$ ping 192.168.0.12 + PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data. + 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms + 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms + ... -"Local host only" mode let's the guest VM and the host machine talk on a -"private subnet" that other devices in your network cannot reach. -Consult the documentation on your virtual machine host environment for -help configuring the options above. +B The ping above is being originated B your B +(main desktop) and going B your guest B, not the +other way around. + +If you are not seeing a valid IP address or it's not responding to pings +(for example, you get error messages along the lines of "Request timed +out", "100% packet loss", or "Destination Host Unreachable"), there +could be a few network-related issues you might need to sort out. See +the section below L +for additional information and troubleshooting advice. + +L Remember this IP address... you will be using it throughout the +tutorial. + =item 6 -B, open an SSH client and connect to -the IP address found in the previous step. You should get a login -prompt (accept the SSH key). Login with the same username and password: -B / B +B, open an SSH client and connect to the +IP address found in the previous step. You should get a login prompt +(accept the SSH key if you get a warning message about that). Login +with the same username and password as we used in Step 4: B / +B + + catalyst login: root + Password: catalyst + ... + root@catalyst:~# + =item 7 @@ -265,18 +285,18 @@ B, change to the sample code directory for Chapter 3 included with the Tutorial Virtual Machine and start the Catalyst Development Server: - $ cd Final/Chapter03 - $ perl scripts/myapp_server -r + $ cd Final/Chapter03/MyApp + $ perl scripts/myapp_server =item 8 -B, open a web browser and go to -B, where C is the IP address to your -virtual machine that you looked up in Step 5. For example, if your -virtual machine is using the IP address C<192.168.0.21>, you would put -the following URL into your web browser: +B (the "host machine"), open a web +browser and go to B, where C is the IP +address to your virtual machine that you looked up in Step 5. For +example, if your virtual machine is using the IP address +C<192.168.0.12>, you would put the following URL into your web browser: - http://192.168.0.21:3000/ + http://192.168.0.12:3000/ Make sure you don't forget the B<:3000> to use port 3000 instead of the usual port 80 that is used by HTTP by default. @@ -299,7 +319,7 @@ install Emacs: =back -You will note that the Tutorial Virtual Machine uses L so +You may note that the Tutorial Virtual Machine uses L so that the Perl modules are run from ~/perl5 (in this case, /root/perl5) vs. the usual location of your "system Perl". We recommend that you also consider using this very handy module. It can greatly ease the @@ -310,6 +330,75 @@ B Perl itself from your home directory [or any other directory you chose]). +=head2 Sorting Out Virtual Machine Network-Related Issues + +In general, using a virtual machine to work through the tutorial is +*much* easier than trying to do it in other environments, especially if +you are new to Catalyst (or Perl or CPAN or ...). However, it's +possible that you could run into a few network-related issues. The good +news is that there is lots of information about the issue available via +search engines on the Internet. Here is some background information to +get you started. + +In Step 5 of the prior section above, we assumed that a "Bridged Mode" +configuration and DHCP will work (it should for most people). If DHCP +is not working or is not available in your location, most virtual +machine "host" environments let you select between one of several +different types of networking between the "guest" and the "host" +machine. + + 1) Bridged + 2) NAT + 3) Local host only + +The Tutorial Virtual Machine defaults to "Bridged" -- this should result +in the VM acting like another device on your network that will get a +different DHCP IP address than the host machine. The advantage of this +approach, is that you can easily SSH and web browse to the guest virtual +machine. In general, this is the best option if you want to be able to +boot up the VM and then use your SSH client and web browser from your +main machine to connect into the virtual machine. + +In some environments, you might have better luck with "NAT" (Network +Address Translation) mode. With this configuration, the guest VM shares +the same IP address as the host machine. The downside of this approach +is that special configuration is required if you want to be able to SSH +or web browse to the guest VM. The NAT option should automatically +allow the VM "outbound connection" (e.g., to the Internet if you want to +install additional Debian packages), but it requires special +configuration if you want to get "inbound connections" that go from some +other machine (including the "host machine") into the VM. Some virtual +machine host environments let you configure a "static NAT" or "port +forwarding" to reach the guest OS, but others omit this functionality. + +"Local host only" mode let's the guest VM and the host machine talk on a +"private subnet" that other devices in your network cannot reach. This +can work as long as you don't need to go from the VM to the Internet +(for example, to install other Debian packages). + +Consult the documentation on your virtual machine host environment for +help configuring the options above. Here are some links that might +help: + +=over 4 + +=item * + +L + +=item * + +L + +=item * + +L + +=back + + + + =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL This tutorial was built using the following resources. Please note that @@ -375,8 +464,8 @@ but if you are running your web browser from outside the Tutorial Virtual Machine, you will want to substitute the IP address of your VM for the C in the URLs (again, you can get the IP address for eth0 from the C command). For example, if your VM has an -IP address of 192.168.245.128, you will want to use a base URL of -C. Note that the development server +IP address of 192.168.0.12, you will want to use a base URL of +C. Note that the development server defaults to port 3000 (you can change with with the "-p" option on the command line.