User Guide - Subversion (SVN)


Applicable Plans: All eApps CentOS 4 or CentOS5 General VPS Plans

User Guide - Subversion (SVN) User Guide

Subversion is an open source application used for revision control. It is sometimes abbreviated to SVN in reference to the name of its command line interface. Subversion is designed specifically to be a modern replacement for CVS and shares a number of the same key developers.
-http://en.wikipedia.org/wiki/Subversion

Note Fedora Core plans do not include Subversion, only CVS is available. CentOS 4 plans have Subversion 1.4.0, and CentOS 5 plans will have the latest version currently offered by eApps (currently version 1.5.6.) If you are on Fedora or CentOS 4 and would like to upgrade to CentOS 5, contact eApps Support for more information.

Overview

This User Guide is designed to help you get started using Subversion on your eApps VPS. This User Guide should enable you to install and configure Subversion, set up a basic repository structure, and access those repositories using the command line svn protocol or by httpd.

This User Guide is limited to the installation of Subversion from the Control Panel of your eApps Hosting service, and the setup of a very basic repository.

This User Guide is not intended as a Subversion tutorial. If you need more assistance that what is offered in this User Guide, please consult the official documentation for Subversion, or one of the many tutorials available online. See the Links to other information section for examples.


Installing Subversion 
  

Configuring Subversion    
Configuring the svn server    
Edit /etc/services    
Add the svnserve file to /etc/xinetd.d     
Create the svnserve directory in /opt     
Restart the xinetd service    
Testing the svn server   

Creating Subversion Repositories     
Adding users to the repo for svn access (not httpd access)    

How to checkout and import files into a repo using svn     

Importing files into an SVN repo     
Checking out files from an SVN repo    

Using SVN+SSH     

Checking out files from an SVN repo using svn+ssh    
Committing files to an SVN repo using svn+ssh    

Setting up Apache(httpd) access to Subversion    

Installing mod_dav_svn    
Configuring mod_dav_svn     
Subversion Repo owner and group for httpd access    

Subversion clients    

Links to other information


Installing Subversion

To install Subversion, log in to the Control Panel, and click on the System Tab. If necessary, click the Select Another System (Subscription) link on the left and choose the correct Virtuozzo container.

If you are not sure if Subversion is installed, go to Applications, and click on All Applications. If you see Subversion in the list, then the application is already installed.

If you do not see Subversion installed, click on Add Application, and click the box next to Subversion, and then scroll down and click the Next button.
 

This takes you back to the All Applications screen. Wait for five minutes, then click on the Refresh link at the upper right, just under the word Parallels. The application should now show as installed. If it is still in a Scheduled state, wait another five minutes, and click Refresh again. If you see it in Error state, or it still shows as Scheduled, please contact eApps Technical Support.


Configuring Subversion

Once Subversion is installed from the Control Panel, it has to be configured to accept connections and to allow access to any repositories that are created.

Configuring the svn server (svnserve)

To access your repositories with an SVN client (either command line or GUI) the svn server must be running. eApps Hosting uses the xinetd service to run the svn server, so it only runs when it is accessed. This saves system resources.

Tech Tip Customers running the CentOS 5 or greater operating system can skip directly to the Testing the svn server section of this User Guide.

To see what operating system (OS) you have, click on the Subscriptions icon from the My Account tab of your Control Panel. Then click on the name of the subscription you want to see. The OS for the subscription will be displayed near the top of the page. If you are not on a CentOS 5 plan, but would like information on updating your plan, please contact eApps Technical Support for more information.

The version of the operating system can also be determined from the command line of the VPS. Assuming you are connected to the VPS via SSH, then as the root user run this command:

cat /etc/redhat-release

That will tell you if you are on CentOS release 4 or CentOS release 5 (there may be a point version, but the major number is what matters).

Note All command line examples in this User Guide must be done from the command line of the VPS while logged in via SSH, as the root user. See the SSH User Guide for more information if necessary. The ability to edit files using the vi text editor is required. 

Edit /etc/services (CentOS 4 only)

The /etc/services file controls what services are available and what ports they run on. See the man page for more information - http://linuxmanpages.com/man5/services.5.php

[root@example ~]# cd /etc/
[root@example etc]# vi services

Add the following two lines to the /etc/services file. The location in the file does not matter. There may already be an entry for svnserve on the same ports - those entries are fine, and can be left alone.

svn             3690/tcp                   # Subversion
svn             3690/udp                   # Subversion

Save and exit the file.

Add the svnserve file to /etc/xinetd.d (CentOS 4 only)

The files in the /etc/xinetd.d directory control the services being run by the xinetd (extended Internet services daemon) service. Add the svnserve file to the /etc/xinetd.d directory. (On CentOS 5 or newer plans this file is called svn, and is created when Subversion is installed)

[root@example etc]# cd /etc/xinetd.d
[root@example xinetd.d]# vi svnserve

Add the following to the svnserve file (copy and paste for best results)

#----------------COPY BELOW HERE---------------#

# default: on
# Subversion server

service svnserve
{
socket_type     = stream
protocol     = tcp
user         = root
wait         = no
disable     = no
server         = /usr/bin/svnserve
server_args     = -i
port         = 3690
}

#------------COPY ABOVE HERE----------------------#

Save and exit the file.

Create the svnserve directory in /opt (CentOS 4 only)

The svnserve directory needs to be created for the Subversion repositories.

[root@example xinetd.d]# cd /opt/
[root@example opt]# mkdir svnserve

Restart the xinetd service (CentOS 4 only)

[root@example ~]# service xinetd restart
Stopping xinetd:                                           [  OK  ]
Starting xinetd:                                           [  OK  ]
[root@example ~]#

Testing the svn server (CentOS 4 and CentOS 5)

Test to make sure that the svn server is listening. If this test fails, then go back and walk through the steps to set up the svnserve file and add the lines to /etc/services.

 Most problems with this step involve something being missed in one of the previous steps. Also, make sure that you do not have iptables blocking the port. If you are still unable to connect to the port after checking over the configuration, please contact eApps Support.


[root@example ~]# telnet localhost 3690
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
( success ( 2 2 ( ) ( edit-pipeline svndiff1 absent-entries commit-revprops depth log-revprops partial-replay ) ) )


Press enter or return to close the connection.


Creating Subversion Repositories

Now that the svn server is running, you can create repositories (repos) for your files, and configure the access to those repos.

This example shows the repos being created from the command line while logged into the VPS via SSH, as the root user. The configuration for the access is also shown from the command line.

It may be possible to create new repos and grant access with your SVN client, but that is completely outside the scope of this User Guide, and totally unsupported by eApps. You will need to read the documentation for your particular SVN client and any other relevant Subversion documentation to determine how to do this.

Use the svnadmin command to create the repo. The svnadmin command has many functions, please see either the svadmin man page or the official Subversion documentation for more information.

Note Make sure to substitute your own repo name for example_repo and your own domain name for example.com  throughout this User Guide

[root@example svnserve]# svnadmin create /opt/svnserve/example_repo
[root@example svnserve]# ll
total 4
drwxr-xr-x 6 root root 4096 Nov 11 12:48 example_repo
[root@example svnserve]#

To create more repos, just run the svnadmin create /opt/svnserve/repo_name command again.


Adding users to the repo for svn access (not httpd access)

To add users that have svn access to a repo, edit the svnserve.conf and passwd files in the conf/ directory of that repo. These are users that have access to the repos from the command line, either from the VPS itself, or from their remote computers. These users can also connect via an SVN client, by using the svn protocol.

Pay particular attention to this section at the top of the svnserve.conf file:

### This file controls the configuration of the svnserve daemon, if you
### use it to allow access to this repository.  (If you only allow
### access through http: and/or file: URLs, then this file is
### irrelevant.)

What this means is that the users and passwords created in the conf/passwd file for that Subversion repo are only relevant when using the svn protocol, not for an httpd or  svn+ssh connection.

Only connections using the svn://example.com/repo_name, either from the command line or an SVN client, will authenticate against this conf/passwd file. Any other connections, such as for httpd or ssh or file will use different authentication methods, and this file will be ignored.

See  the Setting up Apache(httpd) access to Subversion section for information on how to authenticate users with httpd.

[root@example svnserve]# cd example_repo/
[root@example example_repo]# ll
total 24
drwxr-xr-x 2 root root 4096 Nov 11 12:48 conf
drwxr-sr-x 6 root root 4096 Nov 11 12:48 db
-r--r--r-- 1 root root    2 Nov 11 12:48 format
drwxr-xr-x 2 root root 4096 Nov 11 12:48 hooks
drwxr-xr-x 2 root root 4096 Nov 11 12:48 locks
-rw-r--r-- 1 root root  229 Nov 11 12:48 README.txt
[root@example example_repo]# cd conf/
[root@example conf]# ll
total 12
-rw-r--r-- 1 root root 1080 Nov 11 12:48 authz
-rw-r--r-- 1 root root  309 Nov 11 12:48 passwd
-rw-r--r-- 1 root root 2279 Nov 11 12:48 svnserve.conf
[root@example conf]#
[root@example conf]# vi svnserve.conf

Edit the svnserve.conf file, and find these three lines, and uncomment them (the first two lines are right next to each other, the last line is further down the file). Then save and exit the file.

# anon-access = read
# auth-access = write
~
~
# password-db = passwd

Then edit the passwd file in the same directory, and add users and passwords in the same style as shown in that file. In this example the user example_user with a password of examplesecret is added.

[root@example conf]# vi passwd

[users]
# harry = harryssecret
# sally = sallyssecret
example_user = examplesecret

Save and exit the file.


How to checkout and import files into a repo using svn

Using either the command line svn client, or the svn:// protocol in a GUI SVN client, you can import files into the Subversion repo and then check the files out.

Note This is just a very simple and quick example of using the svn command. svn has 25+ subcommands and over 30 switches. For any questions on svn subcommands and their switches, please refer to the official Subversion documentation. Links to the Subversion documentation are in the Links to other information section of this User Guide.

A note for Windows users - there are some Subversion binaries available for Windows, and there are instructions available online on how to use Subversion from the command line on Windows. However, most Windows users use a GUI client like TortoiseSVN for svn:// connections instead of the command line.

Importing files into an SVN repo

This example assumes that you are working on your local computer, at the command line.

To do this, Subversion must be installed on your local computer. Instructions on how to do that are far beyond the scope of this User Guide, but packages for all major operating systems (Windows, Mac OS X and Linux) exist.

A quick search of the web using one of the available search engines will find all the information needed. Links to a few of the available packages are in the Links to other information section of this User Guide.


This example shows a connection to the Subversion repo from a Mac running OS X, importing files into a project directory named example_project in the example_repo repository. The commands on Linux should be identical.

Note that the first authentication attempt was for the username of the Mac OS X user. Hitting return or enter will allow you to use the username and password from the conf/passwd file in the repo.

macbook:~ macuser$ svn import -m "Initial import" svn://example.com/example_repo/example_project

Authentication realm: <svn://example.com:3690> 34b20c70-fca9-4426-b857-32e3d4496b62
Password for 'macuser': press enter
Authentication realm: <svn://example.com:3690> 34b20c70-fca9-4426-b857-32e3d4496b62

Username: example_user
Password for 'example_user': passwd
Adding  (bin)  OODoc.odt
Adding         UG.txt
Adding         README.txt
Adding         html_doc.html

Committed revision 0.
macbook:~ macuser$

Checking out files from an SVN repo

Continuing the example, this shows how to check out files from an SVN repo to your local computer. Again, all of this is done from the command line.

macbook:~ macuser$ svn co svn://example.com/example_repo/example_project
A    example_project/OODoc.odt
A    example_project/UG.txt
A    example_project/README.txt
A    example_project/html_doc.html
Checked out revision 1.
macbook:~ macuser$

Notice that no username or password was requested. This is because in the conf/svnserve.conf file, anon-access =read is allowed. So anyone can checkout (read) the files, but only authenticated users can make any changes to the repo, such as importing files. Setting anon-access = none will stop any anonymous access for checking out the files from the repo.


Using SVN+SSH

It is possible to use SVN and SSH to work with your Subversion repos. Be aware, though, that this approach is for advanced users who are very familiar with the Linux filesystem and user and group permissions. The standard Subversion setup will not work for svn+ssh out of the box; file and directory permissions and ownership have to be adjusted to make this work correctly.

When using svn+ssh, it is SSH that is doing the authentication, not the conf/passwd file in the repo directory. This means that the user that you are connecting as must be a user that already exists on the VPS that is able to connect via SSH. See the SSH User Guide for more information.

For this example, several things have been modified to allow svn+ssh to work. You may find that your situation requires a slightly different setup, depending on what users are trying to connect to the Subversion repo. Remember this is simply an example to show the basic commands, and is not a definitive reference.
  • The webadmin user has been set to allow it to have SSH access (see the SSH User Guide for more information - Adding or modifying users)
  • The example_repo directory under /opt/svnserve has been set to owner:group of webadmin:webadmin.

Checking out files from an SVN repo using svn+ssh

This example assumes you are working from the command line on your local computer. See the previous section titled How to checkout and import files into a repo using svn for more information on the requirements.

Again, this is from the Terminal program on Mac OS X. The same commands should work on Linux.

macbook:~ macuser$ svn co svn+ssh://webadmin@example.com/opt/svnserve/example_repo/example_project

webadmin@example.com?s password: passwd
webadmin@example.com's password: passwd
A    example_project/OODoc.odt
A    example_project/UG.txt
A    example_project/README.txt
A    example_project/html_doc.html
Checked out revision 6.
macbook:~ macuser$

There are several things to note here that are different than the original example using svn only.
  • The full path to the repo must be specified - in the svn example, the path was simply example.com/example_repo/example_project, but with the svn+ssh example, the path to the repo is example.com/opt/svnserve/example_repo/example_project.
  • The username must be specified - unless your user on your local computer and the user on the VPS have the same user name, you will need to specify the user name to connect. Remember that SSH is doing the authentication, not svnserve. This is the webadmin@example.com part of the command.

Committing files to an SVN repo using svn+ssh

Once you have modified the files, they need to be committed back to the Subversion repo.

Since the files were checked out using svn+ssh, the commit will use the same authentication method, even though you do not have to explicitly specify svn+ssh. In this example the UG.txt file was modified.

macbook:~macuser$ svn commit -m "changed UG.txt"
webadmin@example.com's password: passwd
Sending        UG.txt
Transmitting file data .
Committed revision 7.
macbook:~ macuser$


Setting up Apache(httpd) access to Subversion

All the previous examples have used the svnserve daemon to work with the Subversion repos. Apache (httpd) is not actually needed to allow access to your Subversion repos, Subversion is often run on servers that have no web server component installed.

However, you can easily set up Apache to allow access to your Subversion repos. That way, some users can still use the svn command line or SVN clients, and other users can use SVN clients that connect via httpd.

Since Apache is already installed as part of your eApps VPS, the only thing that has to be configured is the access and authentication to the Subversion repos.
This section of the User Guide assumes you have already installed and configured Subversion, and have created a repo or repos to access.

Tech tip Customers running the CentOS 5 or greater operating system can skip directly to the Configuring mod_dav_svn section of this User Guide. The mod_dav_svn module was installed on your VPS when Subversion was installed.


To see what operating system (OS) you have, click on the Subscriptions icon from the My Account tab of your Control Panel. Then click on the name of the subscription you want to see. The OS for the subscription will be displayed near the top of the page. If you are not on a CentOS 5 plan, but would like information on updating your plan, please contact eApps Technical Support for more information.

The version of the operating system can also be determined from the command line of the VPS. Assuming you are connected to the VPS via SSH, then as the root user run this command:

cat /etc/redhat-release

That will tell you if you are on CentOS release 4 or CentOS release 5 (there may be a point version, but the major number is what matters).

The latest version of Subversion for CentOS 4 plans is version 1.4.0. If you are installing Subversion for the first time on a CentOS 4 plan, that is the version you should have available to you. If you are configuring mod_dav_svn for a CentOS 4 plan that already has Subversion installed, please update to the newest version if you are not on version 1.4.0.

The way to check the version is from the command line, as any user:

[webadmin@example ~]$ svn --version
svn, version 1.4.0 (r21228)
   compiled Oct 31 2006, 10:52:34

Installing mod_dav_svn

For httpd access to Subversion to work, the mod_dav_svn module for Apache must be installed and configured, and authentication to the Subversion repos must be set up.

Note All command line examples must be done from the command line of the VPS while logged in via SSH, as the root user. See the SSH User Guide for more information if necessary.
 

Download  mod_dav_svn for Apache with this command (CentOS 4 only)     Note that the wget command should all be on one line.

[root@example ~]# wget "http://repo-centos.eapps.com/centos/4.7/updates/i386/RPMS/mod_dav_svn-1.4.0-1.ep.i386.rpm"
--07:15:21--  http://repo-centos.eapps.com/centos/4.7/updates/i386/RPMS/mod_dav_svn-1.4.0-1.ep.i386.rpm
Resolving repo-centos.eapps.com... 69.89.14.200
Connecting to repo-centos.eapps.com|69.89.14.200|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 73414 (72K) [application/x-rpm]
Saving to: `mod_dav_svn-1.4.0-1.ep.i386.rpm'

100%[========================================================>] 73,414      --.-K/s   in 0.007s

07:15:21 (10.6 MB/s) - `mod_dav_svn-1.4.0-1.ep.i386.rpm' saved [73414/73414]

Then install mod_dav_svn as follows (CentOS 4 only)

[root@example ~]# rpm -ivh mod_dav_svn-1.4.0-1.ep.i386.rpm
Preparing...             ############################## [100%]
   1:mod_dav_svn         ############################## [100%]
Stopping httpd: [  OK  ]
Starting httpd: [  OK  ]

This creates a file called subversion.conf in /etc/httpd/conf.d. and restarts httpd.

Configuring mod_dav_svn 

The configuration file for mod_dav_svn is the subversion.conf file, located in the /etc/httpd/conf.d directory.

The structure of the file is slightly different for CentOS 4 and CentOS 5 users, but the functionality is the same, and the changes to allow httpd access to the Subversion repos are the same.

[root@example ~]# cd /etc/httpd/conf.d/
[root@example conf.d]# cp subversion.conf{,.bck}
[root@example conf.d]# vi subversion.conf


CentOS 4 - uncomment the following line in the subversion.conf file:

#LoadModule dav_svn_module     modules/mod_dav_svn.so

CentOS 4 and 5 - add the following information to the bottom of the subversion.conf file. Create one Location block per repo - meaning that if you have multiple repos in /opt/svnserve, you will have multiple Location blocks in this file.

<Location /repository_name>
DAV svn
SVNPath /opt/svnserve/repository_name
</Location>

So to continue the example, the Location block would look like this:

<Location /example_repo>
DAV svn
SVNPath /opt/svnserve/example_repo
</Location>

Save and exit the file, and restart httpd.

[root@example conf.d]# service httpd restart
Stopping httpd:                                            [  OK  ]
Starting httpd:                                            [  OK  ]
[root@example conf.d]#

If you have made an error in your syntax in subversion.conf, httpd will not restart, and will give an error telling what the problem is. Correct that problem, and restart httpd again.

In a browser, this would be at http://example.com/example_repo (substitute your own domain and repo name)

SVN repo


Since no authentication has been set up for httpd, anyone using an SVN client can checkout and import files into the Subversion repo. This is because the conf/passwd file for the repo only works for svn access, not http access.

To add authentication for httpd access, the Location block for the repo in the subversion.conf file has to be changed. Add these lines to the Location block, between the SVNPath and </Location> lines:

AuthType Basic
AuthName "Example Repo"
AuthUserFile /etc/subversion/svn-passwd-file
Require valid-user

<Location /example_repo>
DAV svn
SVNPath /opt/svnserve/example_repo
AuthType Basic
AuthName "Example Repo"
AuthUserFile /etc/subversion/svn-passwd-file
Require valid-user
</Location>

Save and exit the file, and restart httpd.

The AuthUserFile location and name are not fixed, and can be anywhere on the VPS that a non-root user would have access to. This setup is shown for example purposes. The AuthName is whatever you want to call the repo.

[root@example conf.d]# cd /etc/subversion/
[root@example subversion]# ll
total 0
[root@example subversion]# htpasswd -cm svn-passwd-file example_user
New password: passwd
Re-type new password: passwd
Adding password for user example_user

[root@example subversion]# cat svn-passwd-file
example_user:$apr1$IoY92LdD$Brl.VjmBEpJDVqNnzvnkE0

[root@example subversion]# htpasswd -m svn-passwd-file new_user
New password: passwd
Re-type new password: passwd
Adding password for user new_user

[root@example subversion]# cat svn-passwd-file
example_user:$apr1$IoY92LdD$Brl.VjmBEpJDVqNnzvnkE0
new_user:$apr1$fGevOrYp$MegyRXFh1gT2QdbKnj2jL1
[root@example subversion]#

One important thing to note here is that the first time you use the htpasswd command, use the -cm switch. This creates the file, and uses MD5 encryption.

For any subsequent users, just use the -m switch. If you use the -c switch again, it will overwrite your existing file and replace it with the new user only. All other users will be gone.

Also, be aware that the location of the password file and even the name of the file can be different for each Location block in subversion.conf. There are multiple ways to configure this, and you are not bound by using just what is shown in the examples here for subversion.conf.

Now if you try to connect to http://example.com/example_repo, you will be prompted for a User name and Password. (you may have to clear the browser cache or close and reopen the browser first). Any SVN client that connects to the repo using httpd will also be asked for a User name and Password.

Subversion repo owner and group for httpd access

The last thing to change is the owner and group of the Subversion repository. To allow access to the repo from a client that is using httpd, the owner and group must be changed from root:root (the default) to apache:apache.

[root@example ~]# cd /opt/svnserve/
[root@example svnserve]# ll
total 4
drwxr-xr-x 6 root root 4096 Nov 11 12:48 example_repo
[root@example svnserve]# chown -R apache:apache example_repo/
[root@example svnserve]# ll
total 4
drwxr-xr-x 6 apache apache 4096 Nov 11 12:48 example_repo
[root@example svnserve]#

This change is made because any SVN clients that use httpd will be accessing the repos as the apache user, so that user must be able to read and write to the repo directory.


Subversion clients

There are many different Subversion clients available, both free and not free, for all major operating systems.(For this section, an SVN client refers to a GUI application, not the built-in svn command line client)

One list of Subversion clients is here - http://en.wikipedia.org/wiki/Comparison_of_Subversion_clients and another list is here - http://subversion.tigris.org/links.html#clients

Due to the large number of Subversion clients available, it is not possible for eApps to offer support for any specific Subversion client beyond the most basic of configuration questions.

If you have questions on how to configure and use your particular Subversion client, please read the documentation that came with the client, or contact the vendor for support. Many of these clients have large and active user communities that can assist with any problems.

The Subversion clients that seem to be most used by eApps staff and customers are TortoiseSVN for Windows, and either Cornerstone or Versions for the Mac, all three of which are listed at the second link.. Many Mac users and most Linux users just work from the command line to manage their Subversion repos.


Links to other information

Subversion is a very popular version control system, so there is quite a lot of information available on line for it. The answers to most any question or issue you may have will probably be found by using one of the major search engine sites.

Version Control with Subversion - This is the definitive resource  http://svnbook.red-bean.com/  

Subversion Wikipedia entry - http://en.wikipedia.org/wiki/Subversion_(software)
The official Subversion site - http://subversion.tigris.org/
Subversion cheat sheet - http://www.cheat-sheets.org/saved-copy/subversion-cheat-sheet-v1.pdf
Subversion Quck Reference - http://www.digilife.be/quickreferences/QRC/Subversion%20Quick%20Reference%20Card.pdf
Another Subversion cheat sheet - http://www.digilife.be/quickreferences/QRC/Cheat%20Sheet%20Subversion.pdf
(there are many Subversion cheat sheets and quick reference guides available online )

Mac OS X Subversion package, courtesy of Martin Ott - http://homepage.mac.com/martinott/Subversion-1.5.5.pkg.zip
Windows Subversion packages - http://subversion.tigris.org/getting.html#windows
Other Subversion packages - http://subversion.tigris.org/getting.html

Comments

Please login to comment