Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 12 Next »

 

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.

Unlike production systems, which are frequently fixed at old maintenance levels, the Sandbox is typically kept up to date with the latest system, Java, Eclipse, and JBoss patches. At the time this is written, it is a Centos 7 64 bit operating system with Oracle Java 1.7 64 bit, JBoss EAP 6, and Eclipse Luna. Because Eclipse is not part of the production system, you can upgrade it at any time and install any additional features that aid in development. However, it is probably a bad idea to use Java 1.8 if the production system will be 1.7, and while it doesn't matter much if JBoss is 6.1 or 6.3, you should use the same major version of JBoss that you are using in production (EAP 6.x).

casdev

There is one user named "casdev" with admin (sudo) privileges. You login, run Eclipse, and do all your development as this user. The /home/casdev directory holds the Eclipse workspace and all the casual files. Because JBoss is started from Eclipse, it also runs as casdev. Therefore, the JBoss and Eclipse directories are owned by casdev even though they are installed elsewhere in the file system.

Where

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 /opt 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.

When JBoss is installed in DEV TEST PROD, production services has the licenses to use the RPMs, so different parts of JBoss are scattered into different parts of the system directory structure. For the most part, it doesn't matter if JBoss is completely unzipped into/opt/jboss/jboss-eap-6.2 or has pieces scattered around. It might be important if you want to start JBoss at boot time as a system service, but that is not how development is done. The one directory that matters is the jboss.server.log.dir (the directory into which JBoss puts log files). In production, this is /var/log/jbossas/standalone, but if you just unzip into a single directory it defaults to the log directory that you unzipped. This is changed by setting the parameter explicitly when JBoss is started in Eclipse.

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 be reduced to 1.5 or 2 GB of virtual 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

Setting up the virtual network for the Sandbox is the most complicated configuration option. There are several possibilities, each with advantages and disadvantages.

First, we need to understand some basic Internet network terms. A private network connects some computers or virtual machines to each other, but not to the Internet or the outside world. If you connect computers at home to each other with an Ethernet switch but do not connect a router or a connection to an ISP, then you have a private network. To connect this private network to the outside world you add a cable or DSL modem and a "router" box, but these home routers use a protocol called "NAT". Your home has only one network address assigned to it by the cable or phone company, and all your browsers and mail clients on all your computers have to share it. NAT converts outbound requests from client programs in your home to server programs outside your home so that they all appear to the outside world to be coming from the one IP address managed by the router box. The NAT router connects to the outside service on behalf of the internal client program and it forwards traffic back and forth between the private network and the Internet.

VirtualBox can configure a VM to have a simulated Eithernet adapter that is backed by a NAT service on the host computer. This is a direct connection between the VM on the one end and the host computer on the other end. More than one VM can have a virtual Ethernet adapter that uses the NAT service, but the VMs cannot talk to each other. For that matter, they do not really talk to programs on the host computer either. They simply pass through requests from clients on the VM to servers somewhere on the Yale network or the Internet. From the VMs point of view (if you display network configuration with Linux administration tools) it sees a network with the VM at one end and a NAT router at the other end and nothing else on the network. Of course, the NAT router is connected to the outside world of real computers, but that is outside the router.

VirtualBox can also configure a VM to have a LAN adapter that is "bridged" to the real network of the host computer. The host, after all, has a wired or wireless LAN that connects it to the Yale network and through Yale to the Internet. Every real computer on the Yale network has to be assigned an IP address by Network operations. With a "bridged" LAN adapter, the VM acts like a real computer that shares the real network connection of the host computer. The downside is that the Yale network treats it as a second machine, which means it has to be registered with Network Operations and it has to be assigned its own IP address. This is typically more bureaucracy than anyone needs, although it is a good solution if you are running a Server operating system in your VM and you want other computers to be able to connect to it and use its services. CAS is a server of sorts, but developers generally do not need and in fact do not want other machines to connect to the CAS they are developing.

The VirtualBox "Host-only Adapter" creates a virtual private LAN. First, VirtualBox creates a dummy LAN connector on the host computer. In Windows you get a system dialog asking if you want to install a new device. It looks just like a real LAN adapter, only there is no hardware. Then VMs that are configured to use "Host-Only adapters" each get their own simulated LAN adapter hardware. VirtualBox connects the host computer and the VMs to each other as if all these simulated LAN adapters were plugged into a simulated Ethernet switch. The VMs can talk to the host and to each other, but VirtualBox does not create a NAT function.

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.*.* address. 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).

Desktop computers are not IP routers by default. You have to turn something on. Windows calls this Internet Connection Sharing (ICS) and 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.

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.* 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.
  4. 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 for example) to 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 "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 local browser requests on the same VM).
  • The VMs now have names and network configurations as close as possible to the DEV, TEST, and PROD clusters in the machine room.
  • 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 the Red Hat site.
  • 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.* addresses have no meaning on the Yale network.
  • If you happen to take the laptop home and use this configuration, there is no problem if the LAN address of the real Ethernet adapter is the 192.168.1.* range traditionally used by Linksys routers. The 137 subnet is distinct from the 1 subnet. However, if you use ICS at home instead of a separate router box and your home network is already 192.168.137.* then you better configure the VirtualBox Host-Only adapter to use a different subnet number than 137.
  • CAS requires AD to authenticate netids and passwords. Technically, it requires a configured LDAP server. You could create a dummy LDAP server on your host computer. 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/.

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 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

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.

Centos 7 like Windows has a built in Firewall that might be useful on a desktop machine. In a private virtual network it is useless, and it has been disabled by telling the OS to not start the firewall service ("systemctl disable firewalld"). If you reenable it, then you have to open port 40001 for Ehcache and other ports like 8080 for JBoss.

Clone

The Sandbox VM can be cloned to produce a second CAS VM for testing cluster failover.

Cloning is a VirtualBox operation performed on the VirtualBox control window. Select the machine and choose Clone from the Machine menu. There are two kinds of Clones:

A Full Clone makes a complete copy of the VM configuration and the hard disk. This is the simplest option, but it takes a few minutes to copy the hard drive.

A Linked Clone turns the existing hard disk image into a "snapshot" 13 gigabyte base file, then sets things up so that both the original VM and the clone use that snapshot as a starting point but maintain all changes made to the disk in a separate update file. Since the virtual disk file is not copied, this saves space on your hard disk and the clone is created in seconds instead of taking minutes. However, if you delete the clone and want to convert the original VM back to normal, you have to take a few seconds to delete the snapshot (which merges the changes since the snapshot file was created back into the file creating a single virtual disk file instead of the two files (snapshot and changes).

Once you create a clone, no matter which type you use, any changes that you make have to be duplicated on both systems. This is not a convenient way to do real development, so it is suggested that you create the clone only at the last minute (after you have run CAS Build and CAS Install and are ready to start JBoss) to test cluster configurations, and if you have to edit source and rebuild stuff then you delete the old clone and create a new one.

Every time you create the clone, before starting the clone VM you edit the LAN adapter to change the MAC address from one ending in AD to AE, and after starting the clone for the first time you issue the hostnamectl command as described above to change the hostname. The rest should take care of itself.

CAS Development

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 create a new project using the instructions provided in CAS Development Conventions at Yale.

There are two configured Maven "jobs" in the Eclipse Run - Run Configurations... 

If you click the dropdown mark (V) behind the Run icon on the toolbar (a green circle with a right pointing triangle) then there is a CAS Build job (which runs the Maven POM in the CAS parent directory to compile everything and build the CAS WAR) and a CAS Install job (which copies the CAS WAR to the JBoss deploy directory and inserts parameters into the configuration files). Run the Build first, then the Install. 

Elsewhere on the toolbar there are JBoss Run and Debug icons (a green arrow pointing right and a bug with an arrow under it). They can be used to start JBoss normally or with interactive debugging using Eclipse.

Changing the Sandbox

The Sandbox is separate from the contents of the projects in the workspace or the SVN. You could use the same Sanbox to develop with CAS 3.5.3 or CAS 4.0, and you could probably use it to develop any JBoss hosted application including Shibboleth.

Updating Centos 7 with newer versions of software or changing system configuration options is just standard Linux system administration.

Therefore, changing the Sandbox means installing a different version of Java, JBoss, or Eclipse.

You can install any version of Java using the Oracle RPMs. They go automatically into /usr/java. Generally you configure different versions of Java into Eclipse (Preferences - Java - Java Runtime) and then you select the verison of Java you want to target as a parameter of the Eclipse project, or as a parameter of the CAS Build and CAS Install Run configurations, or as a parameter of the JBoss Server runtime configuration. If you want to change the default version of Java that you get at the command prompt, Google for information on the Linux "alternatives" command.

There are separate instructions in this set of documentation for starting with a vanilla version of Eclipse and then adding the Subversive and JBoss Tools components, so they will not be repeated here.

To install a new version of JBoss, get it from jboss.org and unzip it into a new directory in /opt/jboss. JBoss Tools will configure it automatically if you ask. In Eclipse, go to Preferences - JBoss Tools, JBoss Runtime Detection. Click Search ... and have it search /opt/jboss. It will notice the new server and configure it. To change the default configuration, you need to display the Servers (Window - Show View - Servers). The Servers tab lists all the configured servers. Double click on the name of the server you want to configure. Click the "Open launch configuration" link for detailed startup configuration. In particular, you may want to allow browsers on other machines (actually only on the host computer) to access http://vm-ssoboxapp-01/cas by binding JBoss to the LAN adapter instead of just the local loopback. In the command parameters, change "-b localhost" to "-b 0.0.0.0". Also add  a parameter to change the log directory "-Djboss.server.log.dir=/var/log/jbossas/standalone". If in doubt, compare this to the configuration of another JBoss server.

Disclaimer: configuring modern versions of JBoss AS 7, JBoss EAP 6.x, and Wildfly 8.x are all fairly similar. If you want to configure an older JBoss 5, that changes the entire directory structure and conventions and may require extra research.

 

 

  • No labels