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

Compare with Current View Page History

« Previous Version 24 Next »

Notes for Release 2 Version 4.0

This release is the production test version  of a Docker containerized version of a Shibboleth IdP environment.  Unlike the previous test release, this version enables full access to the Shibboleth configuration environment and, once testing is complete, will be suitable for production use.  The virtual machine contains the tooling needed to build and manage Docker images with your campus configuration, run a pair of Docker Shibboleth IdP images behind a load balancer, make configuration changes, and safely place new versions into production.

Versions of the VM that support environments other than Virtual Box 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, you import the .ova distribution image using the File / Import Appliance function.
  • The default network connection for the Shibboleth IdP packaged 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 you 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.  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 Bridge Mode. Note that is possible to do some testing in NAT mode, but involves the inclusion of port numbers into the process.  This works e.g. https://127.0.0.1:8443 but remember that only one person can use a URL at a time in the TIER Tested. 
  • If you choose to connect this VM to the TIER Testbed, upon success you will see a set of attributes supplied by your Shibboleth IdP VM being displayed by the TIER testbed Shibboleth SP.

Initial Testing Process

A quick test of the environment using the TIER Testbed includes the following steps:

  1. Download the TIER-ShibIdP-R2-V4.ova file (or the most recent version) from the distribution site.
  2. Import the image into virtual box.
  3. Potentially change the network setting from Bridged to NAT - see above comments on VirtualBox.
  4. Potentially change the VM time synchronization setting from UTC to local.  Leave at UTC for use with MacOS and change to Local Time for Windows testing.
  5. Start the virtual machine.
  6. Login to the VM:
    1. LoginId: shibboleth
    2. password: shibboleth
  7. Note the IP address or FQDN of your VM.  You will need this information later.
    1. The standard Linux command: ip addr is available.
  8. cd work
  9. ./setup.sh
  10. ./build.sh
  11. Run: docker ps to verify that the system has started.
  12. Wait for a couple of minutes to give Shibboleth time to start.
  13. Obtain the metadata certificate
    1. Chrome formats the display better than Safari
    2. Browse to https://MY_DOMAIN_OR_IP/idp/shibboleth
    3. The second certificate in the displayed metadata is the one that you need.
  14. In a separate browser
    1. Browse to: https:// testbed.tier.internet2.edu
    2. select the option to Manage testbed metadata
    3. Login via your campus InCommon credentials
    4. Enter your IP address (or FQDN) from Step 7 above in the first box
    5. Copy and paste the certificate from Step 13c above into the second box and press the submit button.
    6. Wait for 10 minutes
  15. While you are waiting, if you have not already created a tested identity, please create one now.
    1. https://testbed.tier.internet2.edu/secure/
    2. Select: Create a new person record
  16. After 10+ minutes have elapsed
    1. browse to https://sp.testbed.tier.internet2.edu
    2. Test your identity provider.

Operational Commands

In order to make changes to the Shibboleth IdP's configuration, cd to /home/shibboleth/build/shibboleth_idp/root and follow normal Shibboleth IdP instructions.

  • docker stop shib_idp_0 shib_idp_1 haproxy
    Shuts down the Shibboleth IdP containers
  • /home/shibboleth/bin/rebuild.sh
    Run this command after making a change to the Shibboleth configuration tree to build your new configuration into the Docker images.
  • /home/shibboleth/bin/restart.sh
    Running this command rebuilds the Docker containers based on your new configuration and sequentially restarts the running containers running behind the load balancer to minimize user disruption. 

  • If you run low on disk space
    • /usr/local/bin/remove-containers.sh

    • /usr/local/bin/remove-images.sh 

  • If you want to save a snapshot of the shibboleth container before making a configuration change, issue the following command:
    • /home/shibboleth/bin/tag/sh my/shibboleth_idp

    • Output will look similar to the following:

      Searching for my/shibboleth_idp image

Image my/shibboleth_idp found

Tagging the container

7313879f2d22-my/shibboleth_idp-161110122546

New docker image tagged $7313879f2d22-my/shibboleth_idp-161110122546
    • In order to revert to the save container, issue the following command (replacing the text in red with the container tag number output in the preceding command):

      • /home/shibboleth/bin/restore.sh my/shibboleth_idp 161110122546

The VM Environment Overview

The VM is designed to support TIER's Docker distribution of the Shibboleth IdP.  The VM can be used to both build Docker containers for use elsewhere and/or be a fully operational environment that is also used to run the containers.  For example, a VM could sit behind a campus load balancer and be one instance of the campus Shibboleth deployment.  The instructions on this page are all geared towards using the VM as your production environment.  Those wanting to use the Docker images directly can review the VM to see how to configure and use them.

The VM contains a full Shibboleth IdP configuration tree located at /home/shibboleth/build/shibboleth_idp/root.  The existing scripting makes changes to this tree but these changes are limited to the initial setup process.  You make operational changes to the Shibboleth IdP configuration by editing the configuration tree in the normal manner (see normal Shibboleth documentation) and running the rebuild.sh command described above.  All Shibboleth IdP configuration information is built into the container, you create a new container to change the configuration.

The operational VM runs three containers: two instances of the Shibboleth IdP and a copy of haproxy.  The haproxy container receives user requests and load balances across the two Shibboleth instances.  The restart.sh script leverages ansible to automate the process of making Shibboleth IdP configuration changes without downtime.  The script works by quiescing traffic to one Shibboleth container, stopping the container, swapping in a new previously built Docker image with the updated configuration, and then resuming traffic to the new container.  This process is then repeated with the second Shibboleth container.

Notes

  1. Virtual Box Console Window
    The console window provided by Virtual box is not over friendly.  The VM accepts SSH on port 22 when the VirtualBox network adapter is configured for a Bridged Adapter and on port 2222 when the VirtualBox network adapter is configured for NAT.   You will find that a SSH connection with a decent terminal emulator is much easier to use.
  2. User Shibboleth does have sudo capability.
  3. User Shibboleth Home Directory
    The shibboleth user's home directory contains the build process and access to make configuration changes. 
  4. Debugging Problems
    The key to debugging issues with Shibboleth remains with the log data,  By default, log data is automatically mapped to the host VM.  In /home/shibboleth/logs you will find access to the usual Shibboleth and Tomcat logs.

Some Useful Docker Commands

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.

  1. docker ps
    Shows the names and status of any running containers.
  2. docker exec
    Run  a command inside a running docker container.  You will find  docker exec -i -t shib-idp bash a handy command for debugging Shibboleth issues.  This command will open a root shell inside the container and map the output back to your VM session.  Inside the container you will find the familiar /opt/shibboleth-idp tree, including access to the configuration and logs. 
  3. docker start
    To start the IdP after rebooting the VM, run docker start shib-idp
  4. docker stop
    To stop the IdP, run docker stop shib-idp
  5. docker cp
    Used to copy files in to or out of a running container.  The syntax is similar to scp.  For example, to copy a logfile to the VM, run the command
    docker cp shib-idp:/opt/shibboleth-idp/logs/idp-process.log .

  • No labels