------------------------------------------------------------------------------ DCVS INSTALLATION ------------------------------------------------------------------------------ PREREQUISITES ------------- The DCVS server is currently only supported on Unix and Unix-like operating systems. This is as well due to the fact that there is no CVSup support for win32 systems, so replication won't work, as to the fact that the CVS server program has not been tested and probably won't work on win32. Of course if you get to run the DCVS CVS server or CVSup on win32, we would like to hear from you and are willing to integrate the changes into our distribution. DCVS can be installed from source and from operating-system-specific binary packages, which install the DCVS system in accordance with conventions of the target operating system. For more information on building and installing binary packages, see the file PACKAGES in this directory. If your operating system is not listed in PACKAGES, you need to install from source. Proceed with installation instructions given in this file. Otherwise, we advise you to build and/or install an installation package for your operating system, as described in PACKAGES, and come back later to the CONFIGURING DCVS section of this file for information about configuring your DCVS installation. You can also find a quick setup guide that assumes you are using binary packages in the file DCVS_IN_30_MINUTES in this directory. If you are installing from source, there should be (must be :-) a dedicated user and group for the DCVS system, for example uid=147(dcvs) gid=147(dcvs) groups=147(dcvs) You should run the DCVSup daemons as this user, and let the dcvs user own several central directories (especially the repositories). The 'make install' phase during installation assumes that this user and group already exist on your system. Binary packages will add a dcvs user and group to your system automatically when necessary. Though DCVS can theoretically be installed in lots of different locations and setups, our source code distribution supports only one default setup: Everything -- except the actual DCVS repositories -- is located under /usr/local/dcvs in the following hierarchy: .../dcvs/VERSION - notice of installed version /bin - all programs (commands and daemons) /doc - documentation /man - manual pages /log - global log files /etc - configuration files and support scripts /etc/dcvs_config - global DCVS configuration /cvsup - global DCVS CVSup configuration /cvsup/sup - DCVS CVSup collection information (can be generated) /dcvsupfile.xxx - CVSup file for host xxx (can be generated) /dcvsupd.sh - generic CVSup daemon start script /dcvsup.sh - generic CVSup client start script /dcvsup_push.sh - generic script to push changes to all other DCVS servers /sdcvsup.sh - generic secure CVSup client start script /sdcvsup_push.sh - generic script to push changes to all other DCVS servers over secure channels /dcvs_sync.sh - generic script to perform a two-way replication /sdcvs_sync.sh - generic script to perform a two-way ssh-encrypted replication [An exception to this rule are binary packages, as described in the PACKAGES file in this directory.] To install from source, you will need several (free) software packages, some common and probably already installed on your system, and some not widely used. Actually the CVS based source part will be content with a standard GNU C compilation tool chain. You can obtain the GNU tools from many FTP and HTTP servers, for example ftp.gnu.org. For (D)CVSup, you need a Modula-3 compiler. All currently existing M3 compilers are based on the free implementation of the former Digital Systems Research Center (DEC SRC), but we suggest to install one of the more up-to-date distributions: PM3: http://www.elegosoft.com/pm3/ CM3: http://www.elegosoft.com/cm3/ EZM3: http://www.polstra.com/projects/freeware/ezm3/ Please have a look at the web sites for all of these distributions to decide which one suits your needs best, as they contain different functionality and support different platforms. in PM3 and EZM3 the compiler is started with `m3build', while the appropriate command in CM3 is `cm3 -build'. The EZM3 distribution is missing the parseparams package which is contained in PM3 and CM3. If you want to build DCVS-CVSup with EZM3, you will need to build and ship parseparams first. As of release 0.1.8, the code is contained in cvsup/parseparams. On 2003-07-29, the tcp packages of CM3 and CVSup, suptcp, have been merged. The suptcp package has been removed from the DCVS CVSup sources; all M3 code now uses directly interfaces of package tcp. The new tcp package is purely an extension of the old one, so there should be no problem with replacing it. For convenience, the new tcp package has been added to DCVS as cvsup/tcp. It is neither compiled or shipped by default though (neither is parseparams). Besides C and M3 compilers, assemblers, and linkers you will need BSD make or GNU make. On Darwin, you may also need to install the archivers/zlib package from fink. INSTALLING FROM SOURCE ---------------------- Create a local working directory, for example ~/work/dcvs: mkdir ~/work/dcvs Change to your working directory: cd ~/work/dcvs Checkout the sources with anonymous CVS or CVSup as described in http://dcvs.elegosoft.com/dcvs/cvs-dcvs-en.php http://dcvs.elegosoft.com/dcvs/cvsup-dcvs-en.php for example: cvs -d :pserver:anonymous@dcvs.elegosoft.com:/usr/distributed-cvs login cvs -d :pserver:anonymous@dcvs.elegosoft.com:/usr/distributed-cvs \ checkout world Alternatively, unpack the source distribution archive, for example tar xzf dcvs-src-0.1.2.tar.gz If you haven't created the dcvs user and group, this would be a convenient time to do so. Change into the production directory: cd prod You can use either GNU make or BSD make (pmake) to build and install all the programs: make all make install The M3 compiler you have installed (CM3, PM3 or EZM3) should now be autodetected. Type make info to see wether the default settings make sense. If you encounter problems due to missing package parseparams or a too old tcp package, you may need to update them with make tcp install-tcp make parseparams install-parseparams You will probably need root permissions for the installation step. INSTALLING FROM BINARY PACKAGES ------------------------------- See the PACKAGES file in this directory. CONFIGURING DCVS ---------------- All pathnames given in this section assume you have installed DCVS in /usr/local/dcvs, which may not be the case if you installed from binary packages. See the PACKAGES file for details on how packages for your system differ from the default setup. DCVS_CONFIG SETUP ----------------- The main work in setting up a DCVS server network is writing a global DCVS configuration file. This file needs to be the same on all DCVS servers. The default name of the DCVS configuration file is /usr/local/dcvs/etc/dcvs_config In it you will declare the following information: 1. The names of all DCVS servers (short ids and fully qualified DNS names). A server configuration line looks like this: server dcvs1 dcvs1.dcvs-net.de 44555 # comment at line end 2. The names of all DCVS clients (short ids and fully qualified DNS names) as well as their local server. A client configuration line looks like this: client workstation1 ws1.dcvs-net.de dcvs1 3. The ranges that distinguish the lines of development based on the RCS branch numbers. A typical range definition looks like this: range base 0..9999 range r1 10000..19999 range r2 20000..29999 range r3 30000..39999 range r4 40000..49999 4. The file collections (CVSup collections and CVS modules) that are elements of the DCVS repositories. A typical collection declaration looks like this: collection libs /usr/dcvs libs dcvs1:base dcvs2:r1:base end The first token after the collection keyword is the collection id (a short arbitrary name), followed by the repository path, followed by the relative collection path inside the repository. This information is followed by a list of server range definitions of the form server-id:range-id[:range-id]* The first pair defines for which range the named server is authoritative, i.e. commit to branches in this range are allowed at that server. If there are multiple range definitions, these are only used by the DCVSup server which passes all related deltas on to other servers. You will have to define all collections before you can do any DCVS operations like importing or adding sources, as DCVS refuses to do anything without a valid collection definition. ENVIRONMENT SETTINGS -------------------- We assume that dcvs1 is our local DCVS server and DCVS has been installed in /usr/local/dcvs. As DCVS will only work in client/server mode, you need to setup either rsh, ssh, or pserver connectivity. We suggest using ssh, as it is the only secure solution: DCVS_RSH=ssh DCVS_SERVER=/usr/local/dcvs/bin/dcvs DCVSROOT=:ext:dcvs1:/usr/dcvs The values give above are of course only examples and need to be customized for your local setup. You should add appropriate values to your shell run commands (e.g. .profile, .bashrc, .bash_login, .cshrc) or central initialization scripts (e.g. /etc/profile, /etc/bash.bashrc, ...). If you use ssh, every user should be able to execute the following command without any unnecessary output: ssh dcvs1 id This should display the id and groups of the user on the DCVS server. REPOSITORY CREATION ------------------- Now you can create all repositories you have referenced in your dcvs_config file with dcvs init: dcvs [ -d :ext:dcvs1:/usr/dcvs ] init [Future versions of cvsupadm will probably have support for creating all needed repositories with default setup.] You should also create the needed locking directories and files with /usr/local/dcvs/etc/dcvs_locks.sh create You can always use /usr/local/dcvs/etc/dcvs_locks.sh check to check the settings. DCVSUP CONFIGURATION -------------------- You can create all needed CVSup configuration files based on your dcvs_config file: cvsupadm create dcvscoll cvsupadm create dcvsupfiles The first command will create all CVSup collection specifications under /usr/local/dcvs/etc/cvsup/sup, the second one will create cvsupfiles for all DCVS servers, for example dcvsupfile.dcvs1 dcvsupfile.dcvs2 These files should be placed in /usr/local/dcvs/etc. Use `cvsupadm help' to learn more about the cvsupadm commands. COLLECTION IMPPORT / ADDITION ----------------------------- You can now use dcvs to import or add files to all the collections for which the local dcvs server is authoritative for. This is the usual CVS usage, so we don't go into details here: dcvs import collection-path vendor-branch release-tag dcvs add ... dcvs commit ... All other deltas will be replicated by the cvsup daemon and client from other DCVS servers. DCVSUP REPLICATION SETUP ------------------------ You can start the local DCVSup server with /usr/local/dcvs/etc/dcvupd.sh We suggest running it as user dcvs. On every DCVS server exactly one instance of the dcvsup daemon should be run. You can start replication in `pull-mode' by executing one of /usr/local/dcvs/etc/dcvsup.sh server-id /usr/local/dcvs/etc/sdcvsup.sh server-id This invokes the cvsup client on the local host and pulls changes from the named DCVS server. The latter form uses a secure channel built by ssh port forwarding. You can push changes that have been committed to the local DCVS server with one of the scripts /usr/local/dcvs/etc/dcvsup_push.sh /usr/local/dcvs/etc/sdcvsup_push.sh These scripts assume that remote cvsup clients can be started via ssh. The latter uses ssh port forwarding to setup secure communication channels. You can do a two-way replication (push and pull) with the following scripts: /usr/local/dcvs/etc/dcvs_sync.sh (clear-text) /usr/local/dcvs/etc/sdcvs_sync.sh (encrypted by ssh) These also work through a NAT-firewall, and the former can be used without having ssh installed. We suggest to setup a crontab for user dcvs on every DCVS server that either pushes or pulls all changes regularly. [Future versions of DCVS will feature simpler setup.] # Local Variables: # mode: text # End: