Fermilab


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:

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

  1. 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..

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

  3. Section removed -- ssh key access is no longer valid

    SETTING UP CVS

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

    1. First make sure you have cvs on your system.
      
            prompt> which cvs
            /usr/bin/cvs
      
    2. 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.

    3. 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:
    1. 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
            
    2. 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:
    1. Contact messier@huhepl.harvard.edu
    2. 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:-
    1. cd /path/to/some/place/
    2. cvs -d minoscvs@minoscvs.fnal.gov:/cvs/minoscvs/rep1 checkout Contrib
    3. cd Contrib
    4. mkdir <your FNAL user name >
    5. 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 core group member should follow these steps:

    1. 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.

    2. 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.

    3. 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

    Access Issues

    Sometimes the cvs server is persnickity about how it is accessed and will fail with an odd error (no example currently on hand). In such cases one modify how the connection is made. In ~/.ssh/config you might try adding:
    Host cdcvs.fnal.gov
         ForwardAgent no
         ForwardX11   no
    
    Host minoscvs.fnal.gov
         ForwardAgent no
         ForwardX11   no
    

    "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.

    "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: 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

    1. 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
          
    2. 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.
        
    3. 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).
      4. Assuming it isn't (c) then make sure ~/.ssh/config has a stanza like:
          Host minoscvs.fnal.gov
          ForwardAgent yes
            
    4. 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.

    OBSOLETE INSTRUCTIONS
  4. Setup your account to use ssh to access the cvs repository

    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.

    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. )

  5. 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:

  6. 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.



Last Modified: $Date: 2012/09/06 20:37:23 $
Contact: minos_software_discussion@fnal.gov
Page viewed from http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/cvs-rep.html
Fermilab
Security, Privacy, Legal Fermi National Accelerator Laboratory