8 Direct SSH Method

We will walk through an example with SSH as the remote shell.

Set CVS_RSH to point to ssh or ssh.exe depending upon the platform. For Windows, if you use a Putty based ssh client, set CVS_RSH to the path to plink.exe

Ensure that your ssh credentials are accessible from the machine you will be running CVS client on. For example if you have a private key, you may want to use the ssh-agent (pageant for Putty) and ssh-add to have ssh pre-register your private key.

Use the bundled cvsrelay executable as the CVS_SERVER. This can be done in two ways:

All client environments should specify an environment variable CVS_SERVER to point to the bundled cvsrelay executable. For example using tcsh :
```
setenv CVS_SERVER <path-to-WANdisco-install>/bin/cvsrelay
```
If you don't want the clients to modify their environment, you can create a link or rename cvsrelay to cvs and modify the PATH so that the ssh daemon (sshd) will invoke cvsrelay instead of cvs when a CVS client connects to it. If sshd is launched via the init.d startup script, you could modify the script that starts sshd to set the PATH to point to cvsrelay bin directory before any other path element. This lets you essentially invoke cvsrelay when a CVS client request comes in. The cvsrelay executable will then be able to relay CVS request/response packets from sshd to WANdisco Security Agent.
```
> cd Security_Agent_root/bin
> pwd
Security_Agent_root/bin
> ln -s cvsrelay cvs
```

Due to security concerns, on most UNIXs sshd is typically compiled with a hardwired PATH. Then setting the PATH in init.d sshd startup script will not work. This can typically be confirmed via:

> strings `which sshd` | grep -i bin
...
/usr/bin:/bin:/usr/sbin:/sbin
...

If you see a colon separated string like above, that might be the compiled in PATH. Alternatively you may look at the first couple of lines in /etc/ssh/sshd_config:

#$OpenBSD: sshd_config,v 1.65 2003/08/28 12:54:34 markus Exp $

# This is the sshd server system-wide configuration file.  See
# sshd_config(5) for more information.

# This sshd was compiled with PATH=/usr/bin:/bin:/usr/sbin:/sbin

If you determine that your sshd has a path hardwired at compilation time you could do one of the following:

Recompile sshd with PATH to cvsrelay ahead of standard cvs executable.
Cleanest approach is to rename cvs to something like cvs.org and change references to cvs in xinet.d/cvspserver to point to cvs.org. Finally link cvsrelay into /usr/bin or any system directory that is on sshd compiled in PATH.

8.1 Authentication with cvsrelay

If you use cvsrelay, you must setup the CVS server's password database in $CVSROOT/CVSROOT/passwd file. The passwords in this file are encrypted using standard UNIX crypt() function so it is possible to cut and paste from /etc/passwd (on some system /etc/shadow)file. Since the authentication is already done via sshd, all we need to do is select a single system password and have all users in the CVSROOT/passwd file share the same password.

In essence the CVSROOT/passwd file would look like:

Bach:1sOp854gDF3DY
Mozart:1sOp854gDF3DY
Handel:1sOp854gDF3DY

All users, as you can see, share the same password. A default passwd file can be copied from Security_Agent_root/config/passwd-template. The template file already contains the default password used by cvsrelay. If you decide to over-ride the default password, you have to modify the configuration (/etc/prefs.conf) for cvsrelay to tell it the new system password to use.

You can also use the bundled utility Security_Agent_root/bin/cvspasswd to generate crypt() password for CVSROOT/passwd file:

$ cvspasswd
Enter CVS password : 
CVSROOT/passwd : sa0Pk81ulv7qc
CVSRelay Password   : 117:99:121:32:73:121:60:121

Also the CVSROOT/config file needs to turn off System authentication:

#Set this to "no" if pserver shouldn't check system users/passwords
SystemAuth=no

# Put CVS lock files in this directory rather than directly in the repository.
#LockDir=/var/lock/cvs

The above scheme is essentially delegating the credentials that were obtained after authenticating with sshd to the cvs server as shown below.

The CVS user authenticates with the SSH daemon, which then invokes cvsrelay with the user ID of the secure shell. This is the user ID that the CVS client transparently passes to sshd. The cvsrelay process in turns looks up the system password at startup time from prefs.conf and passes the user-name and encrypted password to CVS. The CVS server in turn verifies the delegated credentials with entries in CVSROOT/passwd file.

8.2 Configure cvsrelay

The cvsrelay process acts as the bridge between sshd and the WANdisco Security Agent. The prefs.conf file contains the configuration parameters for cvsrelay.

The prefs.conf file is first located in the current working directory (cwd). If it is not found, cvsrelay attempts to locate it in the /etc directory. If it is still not found an error message is logged to UNIX syslog.

The prefs.conf can be automatically generated by the setup tool during the express setup or post-setup using the bundled install-cvsrelay tool.

8.2.1 Using setup or install-cvsrelay

The following are sample screens depicting how setup or install-cvsrelay can auto-generate the prefs.conf needed by cvsrelay.

Specify Security Agent Host name [localhost] : 
You specified localhost, is this correct?[Y|N] [Y] : 

Specify Security Agent port [2409] : 
You specified 2409, is this correct?[Y|N] [Y] : 

Specify CVS pserver host name [localhost] : tao
You specified tao, is this correct?[Y|N] [Y] : 

Specify CVS pserver port [2401] : 2409
You specified 2409, is this correct?[Y|N] [Y] : 

Specify path to the cvs client binary [/usr/bin/cvs] : 
You specified /usr/bin/cvs, is this correct?[Y|N] [Y] : 

Are CVS Clients using WinCVS or TortoiseCVS? Y/N [N] : Y
You specified Y, is this correct?[Y|N] [Y] : 

Enter a valid CVS user on tao [admin0] : user1
You specified user1, is this correct?[Y|N] [Y] : 

Enter any valid CVS Root directory on tao [/home/cvs] : /cvsd/admin0/cvsroot
You specified /cvsd/admin0/cvsroot, is this correct?[Y|N] [Y] : 

Enter CVS password : 

        Creating ../config/prefs-localhost.conf ... [DONE]
        **I: Please copy ../config/prefs-localhost.conf to 
             localhost:/etc/prefs.conf

In order to complete the SSH configuration, ensure:

        1. All cvspserver host:<cvsroot>/CVSROOT/config have the 
           entry "SystemAuth=no".
        2. Copy ../config/passwd-template file to 
           cvspserver host:<cvsroot>/CVSROOT/passwd file 
           and ensure all users added to passwd file have the same password.
        3. Ensure SSH daemon (sshd) is using cvsrelay instead of cvs. 
           See Security Agent admin guide for more details.

8.2.2 Manual configuration

The prefs.conf syntax is name=value pairs. The following parameters can be specified in prefs.conf to customize its defaults:

cvs.port . Defaults to 2401 Specifies the port of the CVS Security Agent to which the CVS requests will be relayed.
cvs.host . Defaults to 127.0.0.1 Specifies the IP address (in IPv4 dot notation, not DNS name) of the Security Agent to forward to. Using the cvsrelay one can run sshd and the CVS server on separate hosts. It is not necessary to collocate them.
cvs.password . Defaults to 117:99:121:32:73:121:60:121 Specifies the octet sequence denoting the system password to pass to the CVS server when delegating the credentials to cvs from sshd. Use the included Security_Agent_root/bin/cvspasswd program to generate password encoded in WANdisco format for cvsrelay. This is done to encode the pass phrase generated by the CVS scrambling algorithm when transmitting cleartext passwords on the wire.
relay.buffer.size . Defaults to 4 KBytes Specifies the buffer size used by the relay. Used to tune the performance of the cvsrelay.
Here is a sample /etc/prefs.conf file:
```
$ cat /etc/prefs.conf 
cvs.port=2401
cvs.host=192.168.1.20
cvs.password=117:99:121:32:73:121:60:121
```

8.2.2.1

TortoiseCVS, WinCVS GUI Clients

When using many of the popular GUI clients with cvsrelay, you may need to patch your cvsrelay installation to make it work. For example when using Tortoise and WinCVS, you may see the following error message:

warning: unrecognized response `Please run install-cvsrelay for this client' from cvs server

If you see the above message, then the administrator needs to run the bundled install-cvsrelay utility. Note this is needed iff you are using cvsrelay.

The install-cvsrelay utility will prompt you for the fully qualified path to the cvs server executable. It will then attempt create a patch specific to the version of cvs server being used. If you install a different version of cvs server at a latter date, be sure to re-run install-cvsrelay.

> cd Security_Agent_root/bin
> pwd
Security_Agent_root/bin
> ./install-cvsrelay

Once install-cvsrelay has patched the prefs.conf, you can then start using Tortoise, WinCVS clients.

8.3 Troubleshooting

Configuring SSH access from CVS clients requires getting the SSH credentials setup correctly as well as configuring the cvsrelay as outlined above.

Here are common gotchas and their solutions:

WinCVS is prompting me for a pass-phrase
Ensure pageant or ssh-agent is running with private keys already loaded, a less secure way is to have no pass-phrase on the private keys at creation time.

How do I know cvsrelay is being invoked?

First check the system log (on Linux /var/log/messages) for any error messages from cvsrelay, for example:

tao /var/log# pwd
/var/log
tao /var/log# grep cvsrelay messages
Dec  1 21:02:04 tao cvs-security/bin/cvsrelay[15105]: failed to open /etc/pref
s.conf
Feb 24 22:03:07 tao ./cvsrelay[5348]: cvs: delegated login failure. Check syslog
 for further info. Server response - "error 0 /tmp/cvstest: no such repository"

You can also setup cvsrelay to run in verbose mode by passing an optional -v parameter:

setenv CVS_SERVER "...../bin/cvsrelay -v"

This will cause the system log (on Linux /var/log/messages) to contain detailed messages from cvsrelay.