Note: This web site is only kept up to date for OSG Software 1.2 (VDT 2.0.0). If you are looking for information for the most recent release, the RPM-based OSG Software 3.0, please see the OSG documentation web site

Using VOMS in the VDT 2.0.0

The Virtual Organization Membership Service (VOMS) stores information about users and their memberships in Virtual Organizations (VOs). The VOMS and VOMS Admin applications allow users and administrators to maintain this information for one or more VOs.

The VDT 2.0.0 version includes VOMS 1.8.8-2p1 and VOMS Admin 2.0.15-1.

To use VOMS in the VDT, you will probably have to perform at least some of the following basic tasks.

VOMS administrators will:

Install VOMS components
Start and stop the VOMS services
Create one or more VOs
Add at least one administrator to a VO
Use the web administration tool to manage a VO

VOMS end users will:

Prepare to use your VO(s)
Obtain a proxy
Get information about a proxy

For more information about VOMS and VOMS Admin, please visit the VDT component page for VOMS.

Installing VOMS Components

Before installation, consider the security of the environment under which VOMS will run, keeping in mind that VOMS controls access to a wide range of grid computing resources. An example of a fairly secure installation is as follows:

Run VOMS and VOMS Admin on a dedicated machine, along with the required Apache, Tomcat, and MySQL
Open ports only for:
- SSH (port 22)
- VOMS Admin HTTPS (default: port 8443)
- VOMS – one per VO (default: start at 15000)
Run no other networked services (e.g., FTP, normal HTTP/HTTPS) on the machine
Use firewalls or other mechanisms to restrict network access to the machine, especially SSH
Use backups, monitoring, and an Intrusion Detection System (IDS)

Our installation instructions will help you install VOMS as you would any other component of the VDT.

There are three VOMS-specific packages that you can select to install:

VOMS-Client: Just the end-user components of VOMS (e.g., voms-proxy-init)
VOMS-Server: Just the server components of VOMS and VOMS Admin, including the administative web application
VOMS: Both client and server components; i.e., both VOMS-Client and VOMS-Server

Several other VDT packages will install all or part of VOMS. For example:

VDT: Installs the complete VOMS package
VDT-Client: Installs the VOMS-Client package
VDT-Gatekeeper: Installs the VOMS-Client package

Starting and stopping the VOMS services

Once VOMS is installed, a system administrator may need to start and stop VOMS services. The preferred way to start and stop services in the VDT is to use the vdt-control command, which installs services into system-wide locations so that the services will be run upon system start-up. However, it is also possible to start and stop services without affecting the rest of the system.

In any case, you must first:

Log in as or become root
Set up your environment to use VOMS (i.e., source a setup script)

Standard Method (vdt-control)

To start services:

vdt-control --on

To stop services:

vdt-control --off

Manual Method (no system-wide changes)

To start services:

$VDT_LOCATION/post-install/mysql start
$VDT_LOCATION/post-install/apache start
$VDT_LOCATION/post-install/tomcat-5 start
$VDT_LOCATION/post-install/voms start

To stop services:

$VDT_LOCATION/post-install/voms stop
$VDT_LOCATION/post-install/tomcat-5 stop
$VDT_LOCATION/post-install/apache stop
$VDT_LOCATION/post-install/mysql stop

Creating a VO

The VDT no longer creates a default VO during installation. Follow the instructions below to create and configure a VO.

Make sure that:
- You are root
- You set up your environment to use VOMS (i.e., source a setup script)
If the VOMS service is running, shut it down:
```
vdt-control --off voms
```
Add the VO:
```
$VDT_LOCATION/vdt/setup/configure_voms --vo VO-NAME --server y
```
where VO-NAME is the name you’d like to give your VO. For more information on the command-line options for configure_voms, please see our reference page.

Allow GUMS to access the VO (if you're ready to let the world know about your VO's users.):

voms-admin --nousercert --vo VO-NAME add-ACL-entry / VO-NAME ANYONE VOMS_CA "CONTAINER_READ,MEMBERSHIP_READ" true

Start services:
```
vdt-control --on
```

Adding an administrator to a VO

Once you have created a VO, you must add at least one administrator to the VO using the command line before using the web administration tools. Only those users whose web browsers present to the web tools an administrator's certificate will be allowed to make changes to the VO.

Make sure that:
- You are root or the user who installed VOMS
- You set up your environment to use VOMS (i.e., source a setup script)
- The VOMS service is running
Add the administrator's user certificate
```
voms-admin --vo VO-NAME create-user CERTIFICATE assign-role VO VO-Admin CERTIFICATE
```
where VO-NAME is the name of your VO, and CERTIFICATE is the path to the administrator's user certificate (often located at ~USERNAME/.globus/usercert.pem).

Do this step once for each administrator you wish to add.
Turn off unauthenticated access to prevent a possible security risk:
```
$VDT_LOCATION/vdt/setup/configure_apache --secure
$VDT_LOCATION/post-install/apache restart
```
By default, VOMS Admin accepts unauthenticated connections from the local machine; this configuration is required to add the first VOMS administrator(s). After that, however, it poses a large security risk: Any local user can become a VOMS administrator and tamper with your VO membership.

To eliminate this security risk, we recommend that you use the commands shown above to disable unauthenticated access after adding the first administrator(s).

After running these commands, an existing administrator will be able to add new administrators at any time using the VOMS Admin web application. But, the voms-admin command will no longer work (unless run as root), because it uses only the unauthenticated channel.

To make Apache less secure again, simply rerun the configure_apache command without the --secure option:
```
$VDT_LOCATION/vdt/setup/configure_apache
$VDT_LOCATION/post-install/apache restart
```

Using the web administration tool to manage a VO

Most basic VOMS administration tasks can be performed using the VOMS Admin web application for your VO. Note: To make changes to the VO, you must have installed your certificate in your web browser and be listed as an administrator in the VO; see the previous procedure for help adding administrators to the VO.

Make sure that:
- The VOMS service is running
- Your web browser has been loaded with your user certificate
Access your local VOMS home page at
```
https://HOSTNAME:8443/
```
where HOSTNAME is the address to the machine on which VOMS is running.
Accessing this URL should show a page that lists your VOs on the right, along with the VDT website links on the left. If, for some reason, accessing this page does not work, or if you'd rather skip this page, you can access your VO’s administrative page directly at
```
https://HOSTNAME:8443/voms/VO-NAME/
```
Follow the links and instructions in the web application to manage your VO

Note: If you receive an error message saying "Access denied", double-check to make sure your browser is loaded with your user certificate and that you have been added to the VO as an administrator.

Prepare to use your VO(s)

If you're an end user, the main reason to use VOMS is to get a proxy certificate for one or more particular VOs. Before doing so, you or your system administrator must make sure your local VOMS software can contact the VOMS server for your VO(s).

Note: If your system administrator set up the VOMS client, they may have also taken care of some or all of the following tasks. Check with them first to see if you need to do anything.

Define your VOMS server(s) in a vomses file (or files)
For each VOMS server you want to use, you must have a vomses file entry that identifies the server and gives it a nickname. Here's an example vomses file entry:
```
"MyVO" "my.voms-hostname" "15000" "/DC=org/DC=doegrids/OU=Services/CN=my.voms.hostname" "My favorite VO" "40"
```
Obtain the vomses file entry or entries you need from your VO administrator(s). You shouldn't have to create the vomses file entries yourself, but if you're curious, the layout of a vomses file entry is as follows:
- Local VOMS name – an arbitrary local label for the VO
- Server host name
- Server port
- Server Distinguished Name (DN)
- VOMS name on the server
- [Optional] The server's Globus version (digits only)
A single vomses file may contain one or more entries, and you may have one or more vomses files. Filenames are arbitrary.

Put your vomses file(s) in a vomses directory; the default vomses directory is ~/.edg/vomses, but you may use any directory as long as you set the VOMS_USERCONF environment variable to refer to it. The vomses directory may contain subdirectories, which will be searched recursively.

There are stringent requirements on the ownership and permissions of the vomses directories and file(s):
- You must own the vomses directory, its subdirectories, and the vomses file(s)
- The vomses directory and any subdirectories must have 0755 permissions
- The vomses file(s) must have 0644 permissions
System administrators: For a VOMS client installation that is available to all users, you can create a central vomses directory at $VOMS_LOCATION/etc/vomses. If you do so, then the vomses directory, its subdirectories, and the vomses file(s) must be have root:root ownership.

Obtaining a proxy certificate

Once you have been added to a VO, you can obtain a proxy certificate for use in submitting jobs as a member of that VO.

Make sure that:
- voms-proxy-init is in your path
- Your user certificate is in its expected location (e.g., ~/.globus/)
Request your proxy certificate:
```
voms-proxy-init -voms VO-NAME
```
where VO-NAME is your VO’s name (as defined in your vomses file – see above)

Note: For more voms-proxy-init command-line options, type
```
voms-proxy-init -help
```
When prompted, enter your user certificate’s password

Here’s some typical output from running voms-proxy-init:

Your identity: /DC=org/DC=doegrids/OU=People/CN=Pat A. Smith 654321
Enter GRID pass phrase:
Your proxy is valid until Fri Dec 09 03:33:33 2005

Creating temporary proxy ............................ Done
Contacting  my.voms.hostname:15000 [/DC=org/DC=doegrids/OU=Services/CN=my.voms.hostname] "MyVO" Done
Creating proxy .................................... Done
Your proxy is valid until Fri Dec 09 03:33:33 2005

Getting information about a proxy

If you have a valid proxy certificate, you can query it for its detailed contents.

Make sure that:
- voms-proxy-info is in your path
- You have a proxy certificate
Get information about your proxy certificate:
```
voms-proxy-info -all
```
Note: For more voms-proxy-info command-line options, type
```
voms-proxy-info -help
```

Here's some typical output from running voms-proxy-info -all:

subject   : /DC=org/DC=doegrids/OU=People/CN=Pat A. Smith 654321/CN=proxy
issuer    : /DC=org/DC=doegrids/OU=People/CN=Pat A. Smith 654321
identity  : /DC=org/DC=doegrids/OU=People/CN=Pat A. Smith 654321
type      : proxy
strength  : 512 bits
path      : /tmp/x509up_u1234
timeleft  : 11:59:00
=== VO VDT extension information ===
VO        : MyVO
subject   : /DC=org/DC=doegrids/OU=People/CN=Pat A. Smith 654321
issuer    : /DC=org/DC=doegrids/OU=Services/CN=my.voms.hostname
attribute : /MyVO/Role=NULL/Capability=NULL
timeleft  : 11:59:00