From Globus

Contents 1 Overview 2 Agreed decisions 3 Decisions that need to be made 4 Ideas 5 Developer guide 6 Status of GS4GT4.2 Documentation 6.1 Sources of Documentation Information 6.2 Documentation Status 6.2.1 *Admin Guide 6.2.1.1 **Building and Installing 6.2.1.2 **Configuring 6.2.1.3 **Deploying 6.2.1.4 **Testing 6.2.1.5 **Security Considerations 6.2.1.6 **Troubleshooting 6.2.2 *Users Guide 6.2.2.1 **Using GridShib 6.2.2.2 **GridShib Commands 6.2.2.3 **Graphical User Interface 6.2.2.4 **Troubleshooting 6.2.3 *Developers Guide 6.2.3.1 **Before you begin 6.2.3.2 **Usage scenarios 6.2.3.3 **Tutorials 6.2.3.4 **Architecture and design overview 6.2.3.5 **APIs 6.2.3.6 **Services and WSDL 6.2.3.7 **Non-WSDL protocols 6.2.3.8 **GridShib Commands 6.2.3.9 **Graphical User Interface 6.2.3.10 **Domain-specific interface 6.2.3.11 **Configuring 6.2.3.12 **Environment variable interface 6.2.3.13 **Debugging 6.2.3.14 **Troubleshooting 6.2.3.15 **Related Documentation 6.2.3.16 **A. GT 4.2.0 Samples for GridShib 6.2.4 *Release Notes 6.2.5 *Public Interface Guide 6.2.6 *Quality Profile

Overview

NOTE: This is NOT the GridShib for GT 0.6.0 documentation.

This is a page to organize the creation of the formal 0.6.0 documentation which is going to be a large change from the previous full release.

Agreed decisions

• We will use docbook

• We will write a small system (most likely m4 based) to generate GT4.0.x documentation and GT4.2.x documentation (from the same source files) that will each stand alone.

• Advanced section is going to be separate from the user's guide. There are many esoteric things that will clutter the basic guide too much.

Decisions that need to be made

• We will be getting a GridShib template for GT4.2.x -- will the full documentation for GS4GT be inserted into this template or will this be a helpful wrapper that points over to gridshib.globus.org for the "meat"?

• We will be getting a GridShib template for GT4.2.x -- if our base documentation source code generates the necessary files to check into the GT doc CVS, will it also live on gridshib.globus.org? The GT4.0.x documentation will, of course.

• TF: I vote yes. This will allow us to release interim releases easily.

(TF: I think the above questions are fundamental to many of the other decisions)

• In the documentation that appears in the GT4.2.x doc tree, do we still refer to the GS4GT version number throughout?

• TF: I vote yes.

• Finalize the major sections we want to present as separate content:

• PROPOSAL 1 (for the moment disregard all those incidental sections in the GT doc template):

• Big picture -- what can this do for you. Relatively short, very clear, and aimed at a wide audience.
• High level technical intro
• User's guide including basic install, configuration, and test.
• Advanced user's guide
• Developer's guide

Ideas

Some unorganized/finer grain ideas:

• Put changelog into CVS and point to it from the docs to keep the content down (one of the main criticisms of the current docs are there is simply too much stuff going on).

Developer guide

This GridShib_for_GT_0_6_0 Developer's Guide preparation page is an unorganized page to put content that will go into the final developer's guide. For the timebeing it will serve as the developer's guide for the work going on in the CVS branch "gridshib_gt_0_6_0_branch".

Status of GS4GT4.2 Documentation

This section covers the status of our documentation in the Globus CVS for the GT 4.2 release.

The online version can be found at http://www.globus.org/toolkit/docs/development/4.2-drafts/security/gridshib/

The GT4 Documentation Primer is invaluable.

Sources of Documentation Information

• This page
• GridShib_for_GT_0_6_0 Developer's Guide preparation
• GridShib_for_GT_Design
• GS4GT 0.5.2 docs
• GS4GT 0.6.0 QuickStart

Documentation Status

http://www.globus.org/toolkit/docs/development/4.2-drafts/security/gridshib/

• Introduction text: Done --Vwelch 19:04, 13 February 2008 (CST)
• Security Key Concepts: Link to non-GridShib docs

*Admin Guide

**Building and Installing

Nothing to be done. --Vwelch 19:21, 13 February 2008 (CST)

**Configuring

Comments from Tom:

• Capitalize words in all headings.

Done --Vwelch 19:37, 13 February 2008 (CST)

• metadataPath: This directory contains any number of trusted entity mapping files.

Added --Vwelch 19:37, 13 February 2008 (CST)

Are any files in this directory used or do they have to following some naming convention?

• For consultDefaultGridmap and samlMapPolicy, see GS4GT 5.2 for relevant doc wording.

I don't find samlMapPolicy, is it perhaps shibAuthzMapFile?

• useVOMS: Not supported in v0.6.0

Gone --Vwelch 19:37, 13 February 2008 (CST)

• enableAttributeQuery: Enables attribute query.

OK. I still need to add an explanation of pull mode somewhere. --Vwelch 19:37, 13 February 2008 (CST)

• In Example, use line breaks liberally when visually formatting XML, otherwise lines break in printed output.

I don't see any other places I can add more linebreaks. Right now all the long lines are long attribute values.

• Section 2: s/a single file/one or more trusted entity mapping files/

Done --Vwelch 19:37, 13 February 2008 (CST)

• Lines too long in Example 2 (but I don't know what to do about it).
• In Example 3, use one of the policy files distributed with 0.6.0 Alpha (not an empty policy file).

**Deploying

Text here but I don't think it is right. I think we just say GridShib is deployed automaticalluy with GT4 and then everything else is configuration. --Vwelch 19:24, 13 February 2008 (CST)

**Testing

**Security Considerations

**Troubleshooting

*Users Guide

**Using GridShib

**GridShib Commands

**Graphical User Interface

**Troubleshooting

*Developers Guide

**Before you begin

**Usage scenarios

**Tutorials

**Architecture and design overview

Comments from Tom:

• Remove trailing "s" in section 3 title.

Done--Vwelch 19:46, 13 February 2008 (CST)

• Section 1: s/GridShib/GridShib for GT/

This seems unnecessary. This is a GT manual, so the fact its for GT seems implicit.

• AttributeAcceptancePIP: Define "Attribute Acceptance Policy."
• SAMLBlacklistPDP: That's the anticipated definition, today we only blacklist based on IP address.

Corrected. --Vwelch 19:46, 13 February 2008 (CST)

• SAMLQueryPIP: GS4GT restricted to Shib AA (not SAML AA), always has.

Done --Vwelch 19:46, 13 February 2008 (CST)

• GridShibPushPDPImpl: VOMS short-circuiting not yet implemented.

Removed --Vwelch 19:46, 13 February 2008 (CST)

• GridShibPullPDPImpl: Loop logic need tweaking, one redundant check by SAMLAttributePDPImpl, I think.

So remove last SAMLAttributePDPImpl invocation?

• Section 4: s/Security Context/SAML Security Context/

Done --Vwelch 19:46, 13 February 2008 (CST)

• Section 4: The SAMLSecurityContext contains more, see the API docs (online).

Online where?

**APIs

**Services and WSDL

**Non-WSDL protocols

**GridShib Commands

**Graphical User Interface

**Domain-specific interface

**Configuring

**Environment variable interface

**Debugging

**Troubleshooting

**Related Documentation

**A. GT 4.2.0 Samples for GridShib

*Release Notes

*Public Interface Guide

*Quality Profile