Versions Compared

Version Old Version 4 New Version 5
Changes made by

Howard Gilbert

Howard Gilbert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

The CAS Development Sandbox VM runs under Oracle Virtualbox (a Yale preferred free VM host) on your desktop or laptop Windows, Mac, or Linux machine. It provides the general setup for using Eclipse to develop an application that will run in JBoss on one or more datacenter VMs. However, it does not try to duplicate the exact setup of datacenter VMs. Production servers are not configured to be friendly for development. Any minor issues that depend on the specific directories into which JBoss is installed can be worked out when you deploy to the DEV environment. The Sandbox simplifies the edit, compile, deploy, and debug cycle.

...

The Oracle Java comes in a standard "RPM" distribution, so it goes into the directory it is preconfigured to use (/usr/local/java). Red Hat official RPMs for JBoss are not generally available, and the public distribution directory supplies a single zip file without further instructions. Eclipse can often be installed from package libraries, but it is also likely to be several releases behind. So JBoss comes from http://jbossas.jboss.org/downloads.html and Eclipse comes from http://www.eclipse.org/downloads/ and they are unzipped into subdirectories of /opt and then assigned to user casdev as their owner.

Eclipse and JBoss could have been put in the casdev HOME directory, but by putting them in public space they could be shared with a second user if you created such an account. Assigning ownership to casdev makes it simpler to add options to Eclipse or to edit the standalone.xml configuration file of JBoss if you need to.

The VM

The VM is a standard Virtualbox 64 bit Linux configuration. With JBoss running the virtual memory use gets up to 1.3 GB, so it could have be reduced to 1.5 or 2 GB of memory if your laptop is constrained.

Install the latest VirtualBox Guest Additions by mounting the CD image and then telling the OS to run the software on the CD.

With a version of Guest Additions built for the kernel you are running that matches the version of VirtualBox you installed on your host laptop, there is a seamless integration between the Sandbox desktop and the host desktop. The VM is configured for bidirectional Clipboard and Drag and Drop, although generally Drag and Drop do not work.

VirtualBox provides a feature called Shared Directory. You can designate a host directory (D:\sandbox is configured by default) that appears to the VM to be a mountable disk/filesystem. When automount is selected, this Windows directory appears to be located at /media/sf_sandbox. While sf_sandbox is owned by root, casdev is in a group that has full access to its contentsvirtual RAM if you need to run two VMs on an 8G laptop.

To use the VM, first install the latest version of VirtualBox from Oracle on your Windows, Mac, or Linux "host" system. Make sure to add the corresponding Oracle VM VirtualBox Extension Pack which contains Oracle code for extra host functions.

The VirtualBox Guest Additions are a set of drivers for the VM operating systems. These mouse, keyboard, video, and filesystem drivers support the integration of the VM interactive environment with the host system. For example, you can cut and paste text between your Windows host and your Centos VM thanks to these drivers. The Sandbox comes with a version of these drivers from when it was built, but if time has passed the version of VirtualBox you just installed will be newer and you should click the menu item Devices - Insert Guest Additions CD. Then autorun the software on the CD image to build the latest version of the drivers.

It is not generally possible to drag and drop files between the Linux and Windows systems. Of course, you can use network file sharing between the machines, but there is a simpler solution. VirtualBox provides a feature called "Shared Folder". In the settings for the VM, there is a section for Shared Folder. You can designate one or more directories on the host computer (D:\sandbox is configured initially for the Sandbox VM). This directory is then given a name ("sandbox" for D:\sandbox). The shared host folder appears to the VM to be a virtual disk or virtual shared disk that can be mounted in Linux or assigned a disk letter (if you have a Windows VM). For Linux VMs, the shared folder is automatically mounted (because of the check box in the VM settings) to the location /media/sf_[name] (that is, /media/sf_sandbox for the name "sandbox"). The casdev user has been added to a group that allows read/write access to the files in the shared folder. This allows easy transfer of files between the VM and the host (Windows?) operating system. Copy files to or from C:\sandbox on the one end, and to or from /media/sf_sandbox on the other end.

The Virtual Network

VirtualBox has several different ways to emulate Setting up the virtual network to which for the VM is virtually connected.

If you have only one VM, then you can use NAT. However, if you have two VMs then they cannot talk to each other.

You can bridge the VM to the real Ethernet adapter. However, then they need IP addresses on what is typically the Yale network. More importantly, they then become visible to the outside world and hackers can try to login to them.

So the best solution is ask VirtualBox to create a virtual Ethernet LAN. This involves creating a virtual Ethernet adapter on the host (Windows?) system that appears to be connected to an Ethernet contain the VMs. VirtualBox calls this a "Host-only Adapter". Your host computer looks like it has two Ethernet adapters to two different networks. The real adapter connects to the real Yale network and the internet, while the VirtualBox adapter connects to one or two VMs.

Following standard practice, the private virtual network is assigned Sandbox is the most complicated configuration option. There are several possibilities, each with advantages and disadvantages. Since a particular developer with specific requirements may have special needs, we should review the options that were not selected and why. You may have different objectives.

The "NAT" option allows the VM to have direct access to the Internet through the host operating system. It is the easiest to configure, but it really works best for one VM. If you work very hard with the port mappings you could get two VMs running this way, but they would be configured strangely and this cannot simulate a CAS cluster.

The "bridge" option allows each VM to appear on the real network as a real computer. It needs a real Yale IP address, which involves bureaucracy with Network Operations. While there are certain development scenarios where you might want a test machine to be public, in most cases this is simply an invitation for some hacker to attack the VM and you often do not lock down the Sandbox as tightly as you would a real server.

The "Host-only Adapter" creates a virtual LAN. There is actually a virtual LAN adapter that appears to the host computer as an additional Ethernet adapter connected to a separate network. The VMs that are configured to use "Host-only Adapter" then get connected to this virtual network. The result is essentially the same as plugging a real LAN adapter into your development computer, then connecting it to a small desktop Ethernet switch and plugging in real computers that are running instances of the Sandbox operating system.

This small virtual private network has to have its own IP addresses, and following the universal convention for home or office private networks we assign a 192.168.*.* IPv4 address range. Windows likes 192.168.137.* for reasons that will become clear below. The host is assigned address 192.168.137.1 and the VMs are 192.168.137.10 (and 11 and so on). The VMs believe that the host 192.168.137.1 is the IPv4 gateway address connecting them to the outside world (Yale and the Internet).

Which then means that you have to turn the host computer into a gateway, and since it has only its one real IP address and the rest of the world does not know about the private virtual network, it has to do NAT. Generally speaking, this is accomplished by Desktop computers are not IP routers by default. You have to turn something on. Windows calls this Internet Connection Sharing (ICS) which is a formal name in Windows and a description of the configuration option on the Macand the Mac has the same feature without the formal name.

On Windows, go to Control Panel - Network and Internet - Network Connections. Right click the real Ethernet adapter (not the VirtualBox Host-Only adapter). Select Properties from the menu. At the top of the dialog there is a Sharing tab. Click the first check box "Allow other users to connect ..." and unclick the second checkbox. Click OK. There will be a large popup warning you (not very clearly) that this is going to change the IPv4 address of the other adapter (the VirtualBox adapter) to 192.168.137.1 and you should only enable sharing if this is OK. Since 192.168.137 is built into Windows, this explains why that particular address was selected for VirtualBox.

Now let us summarize the result of this configuration:

...

ICS is designed for end user client machines. In a home network it allows one desktop machine to share its connection to an ISP with other computers. These days this function is performed by a separate Wireless Router box, so ICS is not widely used any more. Turning on ICS triggers several distinct configuration steps. Because a developer operates in a more complicated environment than the typically home network, it is useful to explain how it works:

  1. Although you configure ICS on the adapter that you are supposed to be "sharing" with other computers, that adapter (the real LAN adapter) is not changed at all. It has the same IP address or continues to get its address from DHCP. It can be a wired LAN, Wireless LAN, or a VPN simulated LAN adapter.
  2. The IP address of the other LAN adapter (the VirtualBox Host-Only adapter) is changed one time only to 192.168.137.1. We have arranged for this to be the right address, but if you don't like it you are free to change it after you turn ICS on.
  3. ICS enables a DHCP server on your Windows host operating system. The DHCP only serves the VirtualBox Host-Only adapter. It vends 192.168.137.*

...

  1. subnet addresses to any VMs that do not have a static IP address assigned to them. However, the Sandbox CAS cluster uses static IP addresses, so it never actually uses the DHCP server. If you change the IP address of the Host-Only adapter to use another subnet, the DHCP server is not reconfigured. It continues to vend 192.168.137.* addresses to the VMs, but now if the host is no longer 192.168.137.1, any VM that uses DHCP will get a useless address and not be able to communicate. Since we do not use DHCP, this is not a problem.
  2. A NAT Router is set up between the two LANs. Any client connection request that comes in from the VirtualBox Host-Only adapter is assigned a new port number and the IP address of the host computer on the real Yale network and is then forwarded to the real server somewhere out on the internet. Traffic between that server and the client on the VM is routed through the host OS between the real Internet and the virtual Host-Only adapter. This NAT function works no matter what IP address the Host-Only adapter has been assigned.

With this technical description that can be understood by someone familiar with TCP/IP and basic internet protocols, now consider the higher level functional result of using Host-Only virtual LAN and ICS:

  • The Virtual Machines appear to be real computers connected to a real but private network. You can interact with them as if they were actual computers and use all the regular network protocols (file sharing, SSH, FTP, HTTP, ...).
  • The VMs have assigned IP addresses and hostnames. The Sandbox VM comes with an /etc/hosts file that maps the names to IP addresses ("vm-ssoboxapp-01.web.yale.internal" is mapped to 192.168.137.1 for example). You should change your host computer "hosts" file (C:\Windows\system32\drivers\etc\hosts on windows, /etc/hosts on other machinesfor example) to include the IP addresses and fully qualified names and nicknames for the machines. Generally speaking, the VMs will have the same /etc/hosts configuration. Then everyone knows how to get to machine "have the same mapping for the same names). CAS cluster configuration then works, and you can use http://vm-ssoboxapp-01.web.yale.internal/cas from a browser on the host computer to test access to the VM CAS, provided that JBoss is started with the parameter that binds it to " (a name just like 0.0.0.0" so it accepts requests from other machines (by default JBoss binds to the loopback address 127.0.0.1 and will only respond to browser requests from the VM).
  • The VMs now have names and network configurations as close as possible to the DEV, TEST, and PROD VMs clusters in the Yale machine room). You can access them with a browser, or SSH, or any other tool just like they were real machines.
  • However, the two VMs are invisible to anyone who is not on the host computer. No other machine can logon to them, or access their Web pages, or hack them.
  • Because the host computer is serving as a NAT router, the VMs can access the Yale network and Internet as clients. They can access the SVN server to commit changes or update source. They can download software updates from vendor sites
  • The network configuration is essentially the same on every developer desktop, yet nothing that one developer is doing is visible to or interferes with another developer even though everyone is using the same "IP addresses" for their private virtual network. It also works if you take your development laptop home, or use it outside of Yale, just as long as you don't try to connect it to a network whose native addresses are Because the virtual Host-Only network is invisible outside the host computer, two developers can be using the same Sandbox configuration on two laptops on the same Yale subnet and they do not interfere with each other. The 192.168.137.* , in which case you are hosed. However, since Yale addresses have no meaning on the Yale network.
  • CAS requires AD or some other LDAP server to validate passwords, you need to be connected to Yale AD from the host computer or else install an appropriate to authenticate netids and passwords. Technically, it requires a configured LDAP server. You could create a dummy LDAP server on your host computer, or temporarily reconfigure CAS to use a different password authentication source. Windows provides AD LDS, but you can use any LDAP server for this purpose. If you want to use the real AD and you need to do so from outside the Yale network, then you need to use a VPN to get access to any real Yale AD. In this case, you install ICS to share the VPN "LAN adapter" instead of the physical LAN adapter. This is sufficiently complicated that it is not recommended (Cisco Anyconnect is just not that reliable).

If you use a Mac or Linux as your native laptop OS, you are going to have to set up NAT routing yourself, although you might Google for "mac nat router" and start at http://www.cyberciti.biz/faq/howto-configure-macosx-as-nat-router/.

For typical development you can use a single VM. To test clustering and failover, you can clone the first VM.  All you have to do on the cloned VM is (before starting the machine) change the MAC Address on the Ethernet adapter from The Sanbox VM image is designed to be Cloned (a VirtualBox operation) to create a second VM for a CAS cluster. There are two hostnames (vm-ssoboxapp-01 and -02) with two IP addresses (192.168.137.10 and 11) on two Ethernet adapters (MAC address 08:00:27:A9:84:AD to one more (change the AD at the end to AE). Then when the machine starts and AE). The distributed VM uses the first hostname, IP address, and MAC address. After cloning it, and before you start the cloned VM, change its MAC address so the last byte changes from AD to AE. When the cloned VM first comes up, issue the following command once:

sudo hostnamectl set-hostname vm-ssoboxapp-02.web.yale.internal

The VM is configured to support both MAC addresses, both hostnames, and both IP addresses (10 and 11)to change the hostname permanently.

If you want more than two virtual machines, then you have to add a new Network adapter configuration in /etc/sysconfig/network-scripts and add a new line in all the hosts files.

CAS Development

There will generally be a cas-server project in the Eclipse workspace, although it may not have current source code. Synchronize it to the SVN directory. However, if CAS development is the same whether you are working on a Windows host computer (with Eclipse and JBoss) or on the Sandbox VM. You edit in Eclipse, build with Maven, and run JBoss from the Eclipse toolbar. Generic CAS develpment is described elsewhere. This section just describes the Sandbox.

When you get a new copy of the Sanbox VM, the casdev user will have an Eclipse workspace in its home directory. This will have a project for the CAS source and for the CAS installer. However, the project may have old files. So the first step is to synchronize the workspace with the SVN server and update the files with whatever is current.

If you are starting work on a whole new release of CAS, then delete the old project and check out and create a new project using the instructions provided in CAS Development Conventions at Yale.

...