MINOS Offline Documentation

[home] [installing MINOS software] [supported platforms] [package links] [mailing list] [HyperNews] [FAQ] [computing help] [MINOS glossary] [archives]

The MINOS Software Repository

The MINOS code lives in a CVS repository on minoscvs.fnal.gov. There are two ways to access the code:

Read-only access via anonymous CVS or "pserver". This is easiest to set up but you will not be able to commit any changes to the code.
Read-write access via SSH. This takes more work to setup but gives you the ability to commit changes back to the repository.

Note that it is possible (and easy) to start with read-only access and convert to read-write access later.

Instructions (based on these), for setting up ssh and cvs follow.

Index

Setting Up SSH
Setting Up CVS
Read Only vs. Read Write access
Notification of Updates
Code Sharing
For Developers
Create a Module
Trouble Shooting
Common Failure Modes

SETTING UP SSH

Check that you have ssh and find where it lives
First figure out if you have ssh installed and what version is installed. Commands the user types are in black.
```
   prompt> which ssh
   /usr/bin/ssh
   prompt> ssh -V
   OpenSSH_3.4p1 Debian 1:3.4p1-2, SSH protocols 1.5/2.0, OpenSSL 0x0090603f
   prompt> which ssh-agent
   /usr/bin/ssh-agent
   prompt> which ssh-add
   /usr/bin/ssh-add
```
If your version of SSH does not support SSH protocol 2.0 it will not work. (Note: SSH v1 has major known security problems which may not have been patched in your version. If you are running v1, you should upgrade to the latest OpenSSH for your own sake.)
If you can't find ssh, ssh-agent, and ssh-add, bug your system administrator. The instructions that follow have been tested for OpenSSH supporting v2 of the protocol..
Skip ahead to the Setting Up CVS if have a kerberos ticket.

The following discussion of ssh key pairs and agents is irrelevant if you have a kerberos ticket. Just remeber to kinit. If you can ssh to the Minos Cluster, you can access CVS. Your kerberos principal does need to be registered with the server, Send mail to kreymer@fnal.gov if your kerberized access fails.

We are considering dropping support for ssh-key access to CVS, perhaps by the end of 2008, for security reasons, and for ease of management.
Setup your account to use ssh to access the cvs repository
Set up an ssh key pair:
```
   prompt> ssh-keygen -t rsa
   Generating public/private rsa key pair.
   Enter file in which to save the key (/home/bviren/.ssh/id_rsa):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/bviren/.ssh/id_rsa.
   Your public key has been saved in /home/bviren/.ssh/id_rsa.pub.
   The key fingerprint is:
   f2:b5:27:f4:ea:cb:48:00:29:1a:72:00:b2:60:89:21 bviren@minos
```
It is best to pick a long but easy to remember and type pass phrase. For example some sentence. Do not use a blank pass phrase, nor your regular account password.
The result is a private and a public key file placed in $HOME/.ssh/. The file names will be based on what type of key you specified. To access the MINOS repository you must use an SSH2 key type ("-t rsa" or "-t dsa")
```
    -t flag	Private key file  Public key file	Protocol, Type
    rsa1	identity	  identity.pub		SSH1, RSA
    rsa		id_rsa		  id_rsa.pub		SSH2, RSA
    dsa		id_dsa		  id_dsa.pub		SSH2, DSA
    
```
( Note: you currently need an SSH1 key as well as an SSH2 key. This is due to a feature limitation on the server-side and may eventually be fixed. In the mean time, besides generating one or more SSH2 keys as above, you should generate an SSH1 key via:
```
   prompt> ssh-keygen -t rsa1
   ...
```
That is, generate a key of type "rsa1" instead of just "rsa". The default file name is ~/.ssh/identity.
Although both SSH1 and SSH2 keys must be forwarded via the ssh-agent (see below) the actual connection is via the SSH2 protocol. )

Get an ssh-agent to run in your interactive sessions

There are a number of ways to make your use of SSH keys easier. With out them you will have to type in your pass phrase every time you access the repository. It will quickly become obvious that it is worth the effort to set up one of these two methods:

Create a per-shell agent:
To get an ssh-agent running in your interactive sessions put this in your shell setup file:

   # For tcsh this goes in $HOME/.login
   if ( ! $?SSH_AUTH_SOCK ) then
      eval `ssh-agent -c`
      ssh-add
   endif

   # For bash this goes in HOME/.bash_profile (or similar)
   # $HOME/.profile
   if [ -z "$SSH_AUTH_SOCK" ] ; then
      eval `ssh-agent -s`
      ssh-add
   fi

This will start the ssh-agent.

To kill the ssh-agent when you're done put this in your shells logout file ($HOME/.logout for tcsh, $HOME/.bash_logout for bash):

   ssh-agent -k

Create a per-X-session agent:
An alternative to the above is to start and stop the ssh-agent with your X session. This is done by adding the following code into your .Xclients, .xinitrc or .xsession files.


#!/bin/sh
# (can use /bin/sh even if your interactive shell is tcsh)

# Start the SSH agent which can hold your keys in memory

eval `ssh-agent -s`


# Call ssh-add to add some keys.  Redirecting /dev/null should trigger
# the use of a graphical password asker (ssh-askpass).  See the man
# page for ssh-add for more details.  Instead of putting this here,
# you can instead add this in your Desktop (eg, GNOME/KDE) session
# startup area.

ssh-add < /dev/null


# Here add any other X initialization, like starting some X clients
# or window manager or desktop.  The below is an example for GNOME.

gnome-session



# when reaching here, the desktop/windowmanager has shutdown, so kill
# off the agent.  Doing the "eval" clears out the environment
# variables created when the agent was first started.

eval `ssh-agent -k`

Email the contents of the generated id_rsa.pub and/or the id_dsa.pub files to Arthur Kreymer. Do NOT send the files w/out the .pub extension. These you should keep secret.
Try to transmit the public key in a way that does not line-wrap as it must be a single (very long) line where ever it is installed.

SETTING UP CVS

Ok, now that you are set up to access the repository using ssh let's set you up to use cvs.

First make sure you have cvs on your system.


      prompt> which cvs
      /usr/bin/cvs

Now you need to set a few environment variables to point you at the MINOS repository. Put this in your usual shell startup file:
```
   # For csh and derivatives
   setenv CVS_RSH ssh
   setenv CVSROOT minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1

   # For sh and derivatives
   CVS_RSH=ssh
   CVSROOT=minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1
   export CVS_RSH CVSROOT
```
See this section for more info on how to access the repository.
Note you should not set the CVS_SERVER environment variable. Commands sent to the minoscvs account must match a strict pattern to be accepted and the value of this variable may result in commands being rejected.
To test whether things worked, try checking something out of the repository. In this example a special directory called CVSROOT is checked out. This directory is needed to perform some other tasks outlined below. Since we use SRT, this is one of the few times you will need to explicitly use CVS to check out a directory.
```
   prompt> cvs get CVSROOT
```
On the off chance you want to get the entire OO repository (with not SRT mechanism in place) you can do:
```
   prompt> cvs get minossoft
```
That should be it. If you have problems, please see the "Trouble Shooting" section at the end of this note.

Read Only vs. Read Write access

As mentioned above, there are two ways to access CVS:

Read-only "pserver" or "anoncvs" connection. Faster, easier to set up, no commits allowed, open to anyone. The CVS root is
```
      :pserver:anonymous@minoscvs.fnal.gov:/cvs/minoscvs/rep1
      
```
Read/write "ssh" connection. Slower, more steps to set up (see above), commits allowed on a per-package basis, only open to MINOS collaborators. The CVS root is
```
      minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1
      
```

One can switch between the two methods both for checking out new code and for changing the access method for already checked out code. New code checkouts are determined by the value of the CVSROOT environment variable. Access for existing code is determined by the value of the CVS/Root file in the directory holding the code. The format of both the variable value and the file contents is the same.

To change the CVS root of existing checked out code use SRT's cvsmigrate command. Its usage is shown via:


   prompt> cvsmigrate --help

For example to change from read-only to read/write cd to the base directory and type:


   prompt>  cvsmigrate -o :pserver:anonymous@minoscvs.fnal.gov:/cvs/minoscvs/rep1 \
                       -d :ext:minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1

One should also be aware that when an SRT "test" release is created or when packages are added it inherits the access method of the associated base release.

Notification Of Updates

To receive e-mail notification of changes made to the repository either:

Contact messier@huhepl.harvard.edu
Check out the CVSROOT directory as shown above and add your email address to one or more of the .list files and commit.

Code Sharing

If you are developing an off-line software package you need to see the section for developers. However, there are often times when people want to use our Repository to share code and other files without the formality of a software package. This is possible by means of a special Contrib "package". This package already has subdirectories for a number of users. To create your own area:-

cd /path/to/some/place/
cvs -d minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1 checkout Contrib
cd Contrib
mkdir <your FNAL user name >
cvs add <your FNAL user name >

You can add further directories within that directory and then populate and commit files.

FOR DEVELOPERS

How do I create a module?

For non-core programmers, to create a new package send a message to a core programmer (or to minos_software_discussion@listserv.fnal.gov if you don't know who this might be). In the message give the following information:

The exact package name.
The user name you used when creating your SSH1 key. In a correctly set up environment, this can be found by doing:
```
    ssh-add -l|grep RSA1|awk -- '{print $3}'
    
```
The RSA1 user names, if any, of others that need write access to the package

The core group member should follow these steps:

Create an empty directory, seed it with a single file and import it as the new package. Non-core users: please don't use the import command directly, ask a core member to do it for you.
```
  prompt> mkdir /path/to/some/place/PackageName
  prompt> cd /path/to/some/place/PackageName
  prompt> touch .cvsignore
  prompt> cvs import minossoft/<PackageName> <vendor tag> <release tag>
```
Notes:
- Obviously, replace "PackageName" with a the name you wish to use for your package. By convention we use StudlyCaps to separate words.
- The empty .cvsignore file is just to prime the package as cvs import will otherwise fail to do anything.
- The directory /path/to/some/place/PackageName is not converted into a CVS controlled directory. It does not need to be named "PackageName", but it should be empty besides holding any files that should be imported. You can simply delete it after the import succeeds.
- It is relatively important to make sure you use "minossoft/YourPackageName" when you do the import. This will assure that the package is placed in the conventional location. If it is left off someone will have to go in and move it in the actual repository - a risky operation.
- The "vendor tag" and "release tag" are required but unused by any thing. Typically one uses the user's name and the string "start", respectively.
Associate a module name with the new package directory. Check out the CVSROOT directory as described above, or update it if you already have one. Then edit and commit the "CVSROOT/modules" file. There are some directions in that file, but it boils down to adding a line like:
```
  YourPackageName        minossoft/YourPackageName
```
Although not necessary for operation, please try to preserve the ordering and sectioning.
Add all the user names that should have write access to this package by editting the "CVSROOT/check_access" file. This is a perl script. Writers are listed in a table that looks something like this:
```
#
# List other writers here
#
  "minossoft/BField",        "costas",
  "minossoft/BubbleSpeak",   "psm",
  "minossoft/DeMux",         "brebel mufson",
```
The format is "minossoft/Package" and "user1 user2 ... ". The users names are as listed in the .ssh/authorized_keys (see above). Note: a common error is to forget the delimiting commas. If this happens no one can commit until someone logs into the server and first fixes it by hand, then commits the fixed version (it is regenerated upon each commit).

TROUBLE SHOOTING

"Precommit check failed for user X"

Before cvs allows changes to be made to the code, it first checks who is allowed to make changes to the package in question. If you are not on this list, your changes are refused.

If X=your name then this means your name is not on this list. If you think you should be, let me know and I can add your name.
If X=minoscvs this probably means that cvs is having a hard time figuring out who you are. One reason for this is that you might not be forwarding your identity. Most versions of ssh do this by default, but some don't. Try this:
```
 ssh -h 
```
If "-A" shows up as a valid command then one way to work around would be to:
```
   setenv CVS_SSH 'ssh -A' 
```
Another would be to specify whether to use forwarding on a per host basis in your .ssh/config file:
```
   Host minoscvs.fnal.gov
        ForwardAgent    yes
```

"Up-to-date check failed"

You may see:

cvs server: Up-to-date check failed for
`the-file'
cvs [server aborted]: correct above errors first!

This means that sometime after you checked out "the-file" in question someone else has committed a change. This means that the file in your directory diverges from the one in the repository.

To correct this do the following:

    cvs update the-file

You will see something like:

    X the-file

Where "X" is one of:

Updated. The file was successfully updated.
Patched. Like the above but a patch was sent instead of the whole file.
M(odified,erged). You have made some modifications to the file which are not yet committed. If the repository copy was also modified, those changes have been successfully merged.
Added. The file is newly added (you won't see this in this case).
Removed. Like above, but removed.
Conflict. Both your copy and the one in the repository have been modified in such a way that CVS is unable to merge them and you need to intervene by hand.

It is this last one that you most need to watch for. If this happens you need to look at your code for blocks delimited like:

<<<<<<< the-file
// your modified code is here
=======
// the modified code which is at the same lines in the repository
// will show up here.
>>>>>>> 1.7

Now, you must go in by hand and resolve this conflict. Typically this means just choosing either your code or the code in the repository and deleting the other (as well as the delimiting lines).

After this hand done merge, you should be able to do another cvs update and see the Modified tag.

If you don't initially see the Conflict tag, then just commit your changes.

COMMON FAILURE MODES

Didn't start your ssh-agent. Check with:

bviren@minos:bviren> env|grep SSH
SSH_AGENT_PID=16463
SSH_AUTH_SOCK=/tmp/ssh-nouUS16462/agent.16462
bviren@minos:bviren> ps auxww|grep $SSH_AGENT_PID
bviren   16463  0.0  0.0  2976  924 ?        S    Dec01   0:00 ssh-agent -s

Didn't load keys into the agent. Check with:

bviren@minos:bviren> ssh-add -l
1024 b6:e0:60:38:f8:fa:39:ed:b4:a4:eb:b3:15:d7:ad:4d  bv@bnl.gov (RSA1)
1024 44:2c:94:c9:33:5d:af:97:50:f7:b4:a5:cf:08:6b:dd /home/bviren/.ssh/id_rsa (RSA)
1024 6c:6a:ef:51:c4:bf:e1:cd:17:b7:51:89:4b:c0:7b:2f /home/bviren/.ssh/id_dsa (DSA)
      You must have an RSA or a DSA (or both) key in order to connect to the
server and an RSA1 key so the CVS script (check_access) can identify you.

Are not forwarding the agent. This can fail to happen in a few ways.
1. The system's global /etc/ssh/ssh_config turns it off
2. You have turned it off in ~/.ssh/config
3. You are using a custom script to invoke ssh (unlikely).
You are using keys other than what have been installed to the CVS account. If this is suspected send the contents of ~/.ssh/*.pub to kreymer@fnal.gov for checking.

Last Modified: $Date: 2008/07/09 22:45:58 $
Contact: minos_software_discussion@fnal.gov
Page viewed from http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/cvs-rep.html


Security, Privacy, Legal

The MINOS Software Repository

Index

Check that you have ssh and find where it lives

Skip ahead to the Setting Up CVS if have a kerberos ticket.

Setup your account to use ssh to access the cvs repository

Get an ssh-agent to run in your interactive sessions

"Precommit check failed for user X"

"Up-to-date check failed"