Contents

Introduction

Apache uses SSH to allow committers to access their home directories on people.apache.org. Please remember to keep your client up to date with security patches. When using SSH to connect to people.apache.org please pay close attention to any known host warnings.

Help Wanted!

Help to finish this document by contributing documentation patches ! If the information you seek isn't in this document, then please submit a patch once the infrastructure folks have answered your question.

Tasks:

  • FIXME: Unbundle those SSH instructions from the CVS instructions.

Available Elsewhere

Note: these resources need consolidating. Help Wanted !

See instructions for new committers to configure your account.

See instructions for setting up SSH on UNIX and Windows.

Troubleshooting

If you encounter a problem with SSH and you are not running the most modern stable release (of the client software you are connecting with) please upgrade and retry.

The client should be configured to use SSH2 where possible. This will ensure that the SSH2 protocol is used to connect to Apache. Not only is this protocol more secure but will allow a chose of interactive keyboard (type in password) or PKI. If you must use SSH1 then you will need to use PKI.

Read this and try to diagnose the problem.

Some Common Problems

Do not expose your private key

Generate your key on a computer that is in your control, then upload only the public part to the people.apache.org server.

Do not make the mistake of generating the key on people.apache.org server.

Too Many Groups

FreeBSD only allows a user to be in 16 groups. An user who is too popular will not be allowed to log on. It is easy to mistake this for a ssh problem. If Authentication succeeded is present in the debug logs then this indicates that the issue lies on the machine login (rather than ssh).

Batch Mode

Batch mode should only be used by automated scripts. You will not be able to login if ssh is configured to use batch mode.

FAQ

What Is SSH2?

The second generation in the ssh family of protocols. It is believed to be more secure than the first generation and the implementations are now mature. Certain flaws exist in the first generation protocols which do not exist in the second generation. SSH2 is therefore recommended.

Most clients can be configured to use SSH2 (where possible).

How Can I Debug My Connection?

The easiest way to diagnose a failing connection is to run your client in verbose mode. This will print up descriptions of the actions that the client is taking. How to do this using OpenSSH is here

If Authentication succeeded is present then this indicates that the issue lies in the machine login (rather than ssh).

How Do I Configure My Client To Use SSH2?

If you are using OpenSSH some instructions are available. Otherwise, please consult the manual.

What Client Can I Use?

Any client that supports the SSH2. (It is possible to use older clients that support only SSH1 but that requires more knowledge.)

OpenSSH is a well known and trusted client that is available for most *nixes. Some notes on how to use OpenSSH to connect to Apache are given here.

What Is PKI?

Public key infrastructure (PKI) enables the ssh family of protocols to operate without passing a password to the server. A passphrase is used to unlock a private key on the client machine. A corresponding public key on the server is used for authentication the during the handshake.

This method of connection is recommended (as the most secure).

Why Can't I Connect Using SSH1?

You can connect to people.apache.org using the SSH1 protocols but only when using PKI

What Is A Known Host?

SSH employs the known hosts mechanism to prevent man in the middle attacks. The first time that the client connects to a server, the fingerprint of the key used by that server is displayed to the user who may to asked to confirm the identity of that server. For example:

The authenticity of host 'people.apache.org (209.237.237.194)' can't be
established.
RSA key fingerprint is 51:85:7d:8f:57:54:e7:6f:27:26:98:7a:c7:c1:47:87.
Are you sure you want to continue connecting (yes/no)? 

The fingerprints for people.apache.org can be found here. If the user elects to continue then this value will be written to a known_hosts file. In future, when the user connects to the same server, this value will be checked and the user alerted if it has changed.

Please do not continue the connection after such an alert: contact infrastructure. This is of crucial importance when using keyboard interactive authentication.

Note: the fingerprint for the key used for ssh is different to the fingerprint of the certificate used to securely serve the website.

What Is A Man-In-The-Middle-Attack?

A class of attacks where the attacker masquerades as the server to the client and the client to the server.

Using OpenSSH To Connect To Apache

OpenSSH is a widely used and trusted suite of software using the SSH family of protocols.

Configuring OpenSSH To Use SSH2 (*nix)

The OpenSSH client uses (by default) configuration files in the ~/.ssh directory. The main configuration file is ~/.ssh/config and is optional. In other words, it may or may not exist already. If it does not then it should be created.

A simple text format is used. Instructions for a particular host (or group of hosts) are grouped together. The following is a suggested basic configuration:

# Apply to all hosts

# Alternatively replace with: 

#Host \*.apache.org
Host \*
  FallBackToRsh no
  Protocol 2,1

There are many other options available.

Debugging An OpenSSH Client Connection

To diagnose what's going wrong with an OpenSSH connection, run the client in verbose mode. To do this just add -v. For example:

$ ssh -v  -l committer people.apache.org