Child pages
  • Linux Preparation for Participants
Skip to end of metadata
Go to start of metadata

Linux Preparation for Participants

This training course is intended for people with limited to no experience with Shibboleth, but having some other fundamental skills will let you focus on learning Shibboleth.

Knowledge required:

  • Basic understanding of XML, specifically how to correctly nest elements and properly close tags
  • Knowledge of your favorite XML Editor, like vim or emacs
  • Basic understating of the Apache httpd and Jetty web servers
  • Basic understanding of authentication, how it's done at your organization, and familiarity with single sign-on concepts
  • Basic knowledge of Linux

Helpful Knowledge to have:

  • Basic familiarity with Java and PHP
  • Basic knowledge regarding how to find and use log files to troubleshoot issues with applications
  • Basic understating of LDAP, specifically your LDAP, its structure, and who to contact for access (especially if it isn't you ☺ )
  • Experience using the Linux command line

Shibboleth requires that messages passed between the IdP and the SP are in close synchronization time-wise. Please ensure that NTP is running. If it is not installed, install it by running "yum install ntp". If the VM clock falls far out of synch with reality, NTP will not change your system clock unless you manually restart the service with systemctl restart ntpd.

Installation on an InCommon-hosted Amazon AWS Instance

You need root (or administrator) access in your host environment to edit the hosts file.  You will be able to use the AWS instances we provide with the InCommon Training SP from anywhere for 2 weeks following your training, such as if you want to revisit the training materials or tinker with it.  Make sure you save anything you want to keep within 2 weeks of the workshop, as we do not back up the instances before we spin them down.

  1. Choose a unique, fully-qualified hostname of the form host.domain.tld. For best results, this hostname should have at least 3 components (two dots). For example, you might choose something like janestestidp.myschool.edu, paulsidp.umaryland.edu, mytestidp.mycompany.com, etc. Throughout this workshop, the instructions will refer to this as my.special.name or MySpecialName.

    The hostname you choose for your VM does not need to resolve anywhere except your own host environment, but it must be unique within the class and it will be visible to the rest of the class. If someone else uses the same hostname as you, bad things will happen™. Please do not use any of the previous example hostnames (in particular, my.special.name) verbatim! Be creative and choose a hostname that you are sure will be unique.

  2. Find out the external IP address of your assigned AWS instance. Typically, the IP address will be part of the instance's DNS name; for example, ec2-12.34.56.78.us-west-2.compute.aws.com would correspond to an IP address of 12.34.56.78. If desired, you can confirm this by looking up the DNS name via a command-line utility like host or nslookup, or any other tool of your choosing.
  3. Edit the hosts file on the host that will be running the web browser(typically your laptop) and in the VM itself at /etc/hosts to assign the hostname you chose in step 1 to your AWS instance's external IP address. For Mac or Linux hosts, the file is located at /etc/hosts; for Windows, it is typically located at C:\WINDOWS\system32\drivers\etc\hosts. Add a line similar to the following, substituting your custom hostname and your instance's IP address:

    12.34.56.78 my.special.name

    If you get permission errors on a Windows host, try right-clicking on the hosts file and select "Open as administrator".

  4. SSH into your instance (using ssh on Mac or Linux, or your favorite SSH client on Windows) using your chosen hostname:

    ssh root@my.special.name

    Check with the instructors for the root password.  Upon login, please change your root password SSH access to something less well-known if this instance will exist for any period of time.  We have no backdoor, so please don't forget your choice.

Installation in a customized environment

If you choose to use a VM hosted in your own environment, please be aware that you will be responsible for addressing any unique environment- or host-related issues. We will try to help but we may be unable to. Participants without sysadmin experience are encouraged to use a provided AWS instance instead.

Select an OS that is supported by the Shibboleth project(or a distribution that is similar) after reading the SP installation instructions for that OS so you know what you're up against. Building from source during the class is a tedious, slow, perilous, and solitary adventure. The instructors are only knowledgeable about supported distributions of Linux.  The AMI we use is effectively just the smallest RedHat-flavored distribution we could prepare.

  • You will need root-level access to a VM with sufficient disk(at least 2GB) and memory(at least 1GB). Please consider using a RedHat-flavored distribution.  If you prefer to use a different distribution, that's fine, as long as you're sufficiently adept working with XML files and Java servlet containers in a shell environment and acknowledge that nobody has any clue what Arch or Fedora will do on any given day, including the trainers.
  • Ensure your VM has a reasonably stable IP address and DNS mapping. You may want to define a custom hostname by assigning your VM a unique, creative fully-qualified hostname of the form host.domain.tld by editing the hosts file in your host environment.
  • Especially if you are using a different distribution of Linuxyou may need to interpret the instructions, which are written specifically for the AWS instances we provide.  MySpecialName will be your VM's hostname.
  • Your VM will need to accept inbound TCP requests from your host machine on 443 (https for users), 8443 (https for services), and 22 (ssh).  It will need to do outbound ldap(389), ldaps(636), https(443), and ntp(123).  Ensure that both your network environment and your host environment permit this from the training on-site.  Obviously, the easiest way to accomplish this is to treat the VM as disposable and open to the world.
  • ssh to your VM and get started.  Install your favorite JDK distribution, but only the official Oracle Java releases are recommended for production by the Shibboleth project.
  • If all else fails, the trainers will be happy to provision an instance for you.  Please ask.
  • No labels