APPENDIX

1. Beginner's Guide to Subversion

1.1 So, what's Subversion?

Subversion is a version control system, a software toolset that helps people to manage changes that are made to collections of shared files. Even when we work alone, most of us will make use of some form of version control, although often crude and inconsistent - such as when we use an application's SAVE AS and cook up a new file name to distinguish the new version from the old. Without version control systems, collaboration (especially in software development) quickly devolves into a horrible mess as different contributors make change to the same files, overwriting or just mangling each others work.

tip" VCS not SCM
There's a specialist form of version control system (called a Configuration Management system) designed specifically for handling software development. Although Subversion is most often used for software development it remains a mainstream version control system that is ready to handle files and documents of pretty much any type, and is occasionally put to novel use, such as managing backups, shared todo lists and even in the writing of collaborative fiction.

Version Control Gives You:

Backup and restore
All changes are recorded and available for retrieval. If you make a mess when changing a file you can get back to the unspoilt version of the file with minimal time and effort.

Synchronization
When you work from a Subversion repository, you are always working with the latest version.

Logging changes
Changes made through Subversion can be documented with messaging that help someone to understand why changes were made.

Playing in the sandbox
Subversion's ability to guard against damaging changes lets you try big risky changes, safe in the knowledge that should you cause a mess, it's easy to go back to the good old stable trunk.

Branching and merging
Development need not take a linear path. With Subversion it's possible to manage multiple version of files at the same time.

Subversion Gives You:

Subversion was originally written by a group of CVS (Concurrent Versioning System) users who were frustrated by CVS's drawbacks. They designed Subversion to build on CVS's stengths, while avoiding its limitations. So when people talk about Subversion's key features, they are usually talking about the things it does that CVS can't do.

Changes to repositories are true atomic operations
Don't worry, there's no radioactivity, that's atomic in the original Greek meaning, as in 'indivisible'. When a change is committed to a Subversion repository it is either fully completed or not done at all. This transactional approach to changes is important for maintaining consistency and protecting against corruption.

Files can't hide from Subversion.
You can rename them, move them or even remove them and Subversion will still track their history.

It's the size of the change in the file, not the size of the file in the change
It's a key property of the Subversion repository model that the cost of an operation is proportional to the amount of change, not the size of the file that is changing.

Branching and tagging are cheap operations
Branches and tags are both handled using a "copy" operation. A copy takes up a small, fixed amount of space. Any copy is effectively a tag. Committing to a copy automatically makes it a branch.

Efficient handling of binary files
Subversion handles binary using a diffing algorithm. So just like with text files, it can store successive revisions of a binary file without having to store a full copy of the file for each revision.

Subversion supports and versions symbolic links
A versioned symbolic link appears as a true symbolic link. On platforms that that don't support them (pre-Vista Windows) they behave like normal files, but Subversion treats the link target as editable.

1.2 How Subversion Works

Subversion uses an approach to versioning called Copy-Modify-Merge which has some big advantages over earlier systems that usually locked files when they were edited to ensure that two people couldn't change a file at the same time. With Copy-Modify-Merge any number of people can make a change to a file at the same time without problem. Each person takes a copy of the file from the repository, this is called a Working Copy and is a snapshot of the file from the latest revision. Changes are always made to this working copy, and when the editor is ready to share the changes, the file is committed back to the repository, where it is given a new revision number.

A file is added to the repository and undergoes a series of changes.

Each time the file is changed and committed to the repository it generates a new snapshot of the file. However, this snapshot is not a full copy of the file, instead it is a diff, which only contains a description of what has changed in the file. The above illustration shows how the changing state of snack.txt is recorded as series of additions and subtractions. No matter what changes are made, or when they are made, it will be possible to recreate any revision by applying the appropriate diffs.

tip" Revision numbers are global, not file specific
The above illustration may give the impression that the revision number is specific to the file, as in snack.txt. In Subversion this is not the case as the revision number reflects any changes that are made within the entire file system. So it's not really revision 5 of snack.txt, more precisely it is the version of snack.txt that appears in revision 5 of the repository, even if it is the only change that was made in revision 5.

Conflicting Changes

So, what does happen when two people make a change to the same file? How does Subversion handle conflicting changes? We'll run through an example situation, illustrated below.

Using Subversion means your food fights leave an audit trail...

1. We checkout a file, snack.txt from the repository, the latest version is Revision 4. The file contains a list of sandwich ingredients. We edit the working copy of the file with our own sandwich preferences.

2. Our colleague, Debs, is already working on snack.txt and commits changes that turn the sandwich into a toastie in revision 5.

3. Having completed our edit of the file, we try to commit our changes, but the commit is rejected because Subversion identified that our revision is out of date, and if our changes are committed, the changes that Debs made in revision 5 will be overwritten.

What an out of date error looks like on the Tortoise Subversion client (on Windows).
4. We attempt an update, this downloads revision 5 of snack.txt and attempts to merge it with our working copy. If the changes between the two versions are in different places within the file there's a good chance that the update will successfully merge the version of the file with revision 5. Unfortunately, in this case the changes can't be merged because the changes happen in the same place. Fear not! We're using Tortoise, the Windows Subversion client which provides some useful tools for dealing with the conflict.

Tip
When Subversion detects a conflict it creates 3 temporary files:

         file.mine (your current working copy)
         file.rOldRev (the file at the revision before your changes were made)
         file.rNewRev (the file as it is in the latest revision in the repository)

Subversion also annotates the original file to show the conflicts within the file (illustrated in the image below).

How a conflicted file is tagged to aid editing.
5. The conflicted file can now be edited so that both sets of changes are included, or whatever solution is best. Either way, Subversion helped stop the loss of work, breaking of files and potential fisticuffs at dawn. In this case, snack.txt is kept as a toastie but is given a mutually agreeable filling.

Tip
After a conflicted file has been fixed, you tell Subversion that the conflict has been resolved. Subversion will then delete the three temp files and allow the file to be updated or committed.
Conflicts rarely occur if you remember to do an update of your local copy before making any changes.

The log view of snack.txt showing the changes over.

1.3 Directory structure

Subversion doesn't force you to organize your files in any particular way, although there is a best practise for how to keep Subversion repository files. This isn't essential, but as the term 'best practise' suggests, everyone agrees this is a good way to work - especially those who started out by ignoring it and ended up in a mess.

A repository created with the recommended directory structure.

.svn

Prior to Subversion 1.7, every directory in a working copy contains a administrative directory called .svn. The files in each administrative directory help Subversion recognize which files contain unpublished changes, and which files are out of date with respect to others' work. There's never any good reason for entering the directory and making any manual changes - just leave it alone.

Subversion 1.7 contains a rewritten Working Copy Library (called WC:NG). This does away with seperate .svn directories, using instead a single .svn directory located in the repository's main directory.

** Alert! ** Alert
Don't delete or change anything in the .svn directory! Subversion depends on it to manage your working copy. If you accidentally remove the .svn subdirectory, the easiest way to fix the problem is to remove the entire directory (a normal system deletion, not svn delete), then do an svn update from a parent directory. The Subversion client will pull in a fresh copy of the directory you've deleted, along with a new .svn folder.

Trunk

The trunk directory is for current development code. The name is a reference to a growing trunk of a tree, not a place to store your spare tyres. This is where your current release code should be stored. It's best not to muddy the Trunk directory with revisions or release names.

http://10.2.5.2:9880/encom/trunk

Branches

Growing off the trunk are your branches. Branches, like the branches of a tree are "offshoots" of the trunk. The idea is to use branches to work on significant changes, variations of code, without causing disruption to the current release code.

Bug fixing on a branch.

A major bug might be fixed on a branch created for this purpose. This allows for bug fixing changes to be worked on without the potential for disrupting other work going on in the trunk/development branches.

"Toe in the water" branches

It's common to use a branch as a code "sandbox" when you want to try a new technology out. If everything gets broken, you can walk away, with no risk to the working code, but if the experiment works out, it can be easily merged back into the trunk.

http://10.2.5.2:9880/encom/branches/R1.02
http://10.2.5.2:9880/encom/branches/soapflax

2. Using LDAP for authentication

LDAP stands for Lightweight Directory Access Protocol. It's a kind of database language that is optimised for handling information look-ups, ideal for an organisational address book, or in this case an authentication directory that controls user access to an organisation's systems, such as Subversion repositories.

Lightweight, you say? To the uninitiated, LDAP looks a bit involved, and some question whether it could be described as lightweight. But, compared to its predecessor, X.500, LDAP is in fact much more lightweight. X.500 doesn't use the Internet standard TCP/IP protocol, has very convoluted naming conventions, and requires a lot of resources to implement. LDAP keeps most of X.500's good stuff, but is simpler to setup and use.

2.1 How LDAP works

LDAP arranges information in the form of a hierarchical tree, made up of entries which are themselves made up of a number of attributes. At the top of the tree are the top level entries such as organisation, country or company with lower level entries dealing with people, products or systems etc. Some LDAP directories use the Internet domain naming system for their arrangement which allows for directory services to be located using the DNS.

LDAP example

The above illustration shows a simple directory for 'thecompany'. Entries are identified using globally-unique Distinguished Name (DN), which allows each entry to be referenced without fear of duplication or ambiguity. The DN of an entry is formed by taking the name of the entry, called the Relative Distinguished Name (RDN) and concatenating the names of the entries that sit above it on the directory tree.

example
Chell Glidewell's LDAP entry has an RDN of uid=cglidewell
The DN is uid=cglidewell,ou=People,dc=thecompany,dc=com.

Each of the entry's attributes has a type and one or more values. The types are typically mnemonic strings, like "cn" for common name, or "mail" for email address. Different attributes use different syntax. For example, a cn attribute might contain the value Chell Glidewell. A telephoneNumber attribute might contain the value "+1 299 299 8911".

LDAP lets you control which attributes are required for an entry, using a special attribute called objectClass. The values of objectClass determind the schema rule for the entry.

3. Setting up SSL

Subversion MultiSite Plus supports the use of Secure Socket Layer encrytion (SSL) for securing network traffic. Currently you need to run through the setup during the initial installation. If you plan to use SSL you need to run through the following steps before starting the SVN MultiSite Plus installation.

1. Open a terminal and navigate to <INSTALL_DIR>/svn-replicator/config.

2. Within /config make a new directory called ssl.

-rw-rw-r-- 1 wandisco wandisco 5 Dec  5 13:53 setup.pid

[User@Fed11-2 config]$ mkdir ssl

3. Go into the new directory.
```
cd ssl
```

4. Copy your private key into the directory. If you don't already have keys set up you can use JAVA's keygen utility, using the command:
```
keytool -genkey -keyalg RSA -keystore wandisco.ks -alias server -validity 3650 -storepass  <YOUR PASSWORD>
```
Knowledgebase
Read more about the Java keystore generation tool in the KB article - Using Java Keytool to manage keystores

-genkey

Switch for generating a key pair (a public key and associated private key). Wraps the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.

-keyalg RSA

The key algorithm, in this case RSA is specified.

wandisco.ks

This is file name for your private key file that will be stored in the current directory.

- alias server

Assigns an alias "server" to the key pair. Aliases are case-insensitive.

-validity 3650

Validates the keypair for 3650 days (10 years). The default would be 3 months

- storepass <YOUR PASSWORD>

This provides the keystore with a password.

If no password is specified on the command, you'll be prompted for it. Your entry will not be masked so you (and anyone else looking at your screen) will be able to see what you type.

Most commands that interrogate or change the keystore will need to use the store password. Some commands may need to use the private key password. Passwords can be specified on the command line (using the -storepass and -keypass options).
However, a password should not be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system.

The utility will prompt you for the following information
```
What is your first and last name?  [Unknown]:  
What is the name of your organizational unit?  [Unknown]:  
What is the name of your organization?  [Unknown]:  
What is the name of your City or Locality?  [Unknown]:  
What is the name of your State or Province?  [Unknown]:  
What is the two-letter country code for this unit?  [Unknown]:  
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?  [no]:  yes


Enter key password for <mykey>
(RETURN if same as keystore password):
```
5. With the keystore now in place, the setup will pick the file up if you provide the relevant details during the installation process.

Changes in these value require a restart. Any invalid value will restart the replicator and no DConE traffic will flow.

SSLv3 is support (though not enforced). If your browser setting has SSLv3 disabled, you will get a handshake error message. If it has both SSLv3 and TLS enabled, then, depending on the browser, it will try to switch from TLS to SSLv3 during the handshake. If you receive a handshake error message in your browser, make sure that TLS is disabled and only SSLv3 is enabled. All current browsers support SSLv3.

3.1 Setting the server key

In the keystore, the server certificate is associate with a key. By default, we look for a key named server to validate the certificate. If you use a key for the server with a different name, enter this in the SSL settings.

3.2 SSL Troubleshooting

A complete debug of the SSL logging will be required to diagnose the problems. To capture the debugging, run the java process with:

'-Djavax.net.debug=all' flag.

To enable the logging of SSL implemented layer, turn the logging to FINEST for 'com.wandisco.platform.net' package.

3.3 Using SSL for both LDAP and emails

If you're specifying secure email (using a truststore) and LDAP authentication over SSL (using a truststore), the same truststore must be used for both sets of certificates. If different truststores are used then the LDAP truststore will overwrite the email truststore and secure emails will stop working.

SVN MultiSite Plus
Last doc build: 16:12 - Tuesday 29nd January 2013