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

Compare with Current View Page History

« Previous Version 17 Next »

Background

The TIER Grouper Virtual Machine software release is a Docker container-based virtual machine distribution that includes the ability both build the appropriate set of Docker containers and run the containers to provide a Grouper service.  The operating environment includes appropriately Grouper and MariaDB containers networked together to build the Grouper service.  The current distribution is based on Oracle VirtualBox.  Other VM environments will be made available in the future.

A few words on VirtualBox

  • If you are not familiar with VirtualBox, you can read the documentation and download the software from Oracle's  web site .
  • Once VirtualBox is installed and running, import the .ova distribution image using the File / Import Appliance function.
  • The default network connection for the packaged Grouper Virtual Machine is Bridged. With a bridged network connection, the VM will use dhcp to obtain its IP address from your local network.  If you have a network registration process in place on your campus network, you may need to register the MAC address of your VM before it is able to obtain an IP address.  You can change the VirtualBox network configuration to NAT mode to look at the VM and its components this way but it is not recommended for general testing or production use.  Remember, if you are on a public network, the VM will be exposed to the world and we publish the password on this web site.  Note that Virtual Box bridge mode can not work with many wireless network adapters since the don't support promiscuous mode.  A wired network connection is generally better for use with Bridged mode.

Setup Process

When you complete the process itemized below, you'll be able to see and login to the Grouper management page.

Once you have started the VM, login to the account grouper with a password of grouper.  You can then use the Linux ip addr command to determine the IP address that has been assigned to your virtual machine.  You will need this address (or its matching DNS name, if any) later in the process.  We also recommend that you use a ssh client to login to the vm instead of using the terminal emulator provided by VirtualBox.  The VirtualBox terminal emulator is very limiting.

Issue the following commands to configure Grouper:

cd work
./setup.sh

 

 

The setup.sh script generates a new key-pair, a certificate signing request, and a self-signed certificate.  The script installs the self-signed certificate into /home/grouper/build/grouper/certs where it will later be built into the Docker container.  For a production environment, you must take the certificate signing request from /home/grouper/work/crypto/server.csr, have it signed by a commercial CA, and place the resulting certificate in /home/grouper/build/grouper/certs before moving on to the next step.

Notewell: Virtual machines start will little to no entropy for the random number generator.  If your build is for a production environment, be sure to run the VM for a while, moving data, etc., before running the setup.sh script.



Issue the following commands to build the containers:

cd /home/grouper/build/grouper
bin/build.sh

 

 

Issue the following commands to run the containers:

cd /home/grouper/run/
bin/run.sh

Setup.sh Log Example

vm>cd /home/grouper/work

vm>./setup.sh

Welcome to the TIER Grouper Virtual Machine

Note: if you are running this script to set up a production Grouper instance, please be sure that you have had this VM running for a sufficiently long period of time, with network traffic reaching reaching the VM in order to build entropy before keys are generated.

The Grouper IdP requires the use of Oracle Java.  This VM is configured to download it for you as part of the Docker image build process, but, before we proceed, you must agree to the Oracle Binary Code License Agreement for Java SE.  Please review: http://www.oracle.com/technetwork/java/javase/terms/license/index.html

Do you agree to the terms of the Oracle license [Yes/No]? Yes

 

Please supply the Fully Qualified Domain Name (FQDN) of your Grouper IdP.

We will use the information you enter here to configure your IdP. Note: for testing without DNS support (a common case), simply enter the IPv4 address of your VM at the prompt below

Enter the FQDN or IP address of your server: 137.54.129.75

You entered: 137.54.129.75    Is this correct [Yes/No]? yes

SSL certificate: enter value for country: US

SSL certificate: enter value for State of Province: Michigan

SSL certificate: enter value for Locality: Ann Arbor

SSL certificate: enter name of your organization: Internet2

Hit ctrl-C in the next 10 seconds to abort the process.

Please do not abort the script is doing work, you can rerun when its complete if needed

Configuring for the download of Oracle Java

Generating certificates for Grouper

 

A self-signed certificate for Grouper is stored in: /home/grouper/etc/certs For production use, replace this certificate with one signed by a commercial CA the Certificate Signing Request for the commercial CA is located at: /home/grouper/work/crypto/server.csr

Preliminary setup is complete

 

For production use, please review the files in: /home/grouper/run/conf The common.env and grouper.env files contain passwords that need to be site secrets for production use

Once you have made any other needed edits, cd to /home/grouper/build/grouper and execute bin/build.sh

When the build is complete, cd to /home/grouper/run/ and execute bin/run.sh

*** Wait for grouper to start. This can take a couple of minutes the first time

Then browse to: https://137.54.129.75/grouper/

Note: your first connection to this URL will be very slow and may time out - try again - be patient.

Verification Process

The first step is to be patient and wait.  The first-time startup of Grouper can take a couple of minutes.  Wait two minutes before starting on the next step.

  • Browse to: https://YOUR-IP-OR-DNS/grouper/
    • Note: your first connection to this URL will be very slow (minutes are not unusual)
    • If your browser times our, just retry the connection,
  • Login as the Grouper Administrator
    • Login Name: GrouperSystem
    • Password: XXXXXXXXXX

If you are not familiar with Grouper, please review the on-line Grouper Training and other documentation.

  
  • No labels