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 appropriate Grouper and MariaDB containers networked together to build the Grouper service. The current distribution is based on Oracle VirtualBox, though an Amazon AMI is available which can easily be shared, but is not yet public. The VirtualBox VM can be downloaded here.
These notes are for TIER-Grouper Release 17040. Release 17040 of the TIER-Shibboleth-IdP appliance contains the following components:
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 (e.g. ssh, putty, or securecrt) to login to the vm instead of using the terminal emulator provided by VirtualBox. The VirtualBox terminal emulator is very limiting.
Note: You should change the password for the linux account grouper, especially before placing the VM on a public network. If you fail to change this passwords, your VM might be compromised. The user comanage has sudo capability. We recommend that you change this password now by issuing the following command:
Issue the following command to configure Grouper:
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, typing, causing randomness, etc., before running the setup.sh script.
Issue the following command to build the containers:
Issue the following command to run the containers:
Setup.sh Log Example
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.
Grouper requires that you use 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 ("Oracle License"). Please review:
By agreeing to the Oracle License, you acknowledge that Internet2 is not distributing the Java software and, to the extent an issue arises related to your use of Oracle Java in the TIER software package, you and Internet2 agree to hold each other harmless from any third party claims.
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: 184.108.40.206
You entered: 220.127.116.11 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://18.104.22.168/grouper/
Note: your first connection to this URL will be very slow and may time out - try again - be patient.
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.
While the normal idea is that you should never need to look inside a container, it is possible and is sometimes useful for debugging unusual issues. These commands may be helpful.