[[PageOutline]]

= dasscm =

'''dass''' '''c'''onfiguration '''m'''anagment (dasscm) is a simple solution for managing system configuration file with Subversion. It is favored because of its easy setup and low footsprint. It can be easily integrated into Nagios monitoring. 

== Features ==

 * version file directly on the target system. Keeping track of the Subversion checkout is done automatically in the background
 * work with your system id, but checkin files with your Subversion id
 * easy status check (checks if all files are checked in). Easy integration into Nagios

[[TitleIndex(dasscm)]]

== Installation Repositories ==

|| package downloads || http://software.opensuse.org/download/package?project=home:dassit&package=dasscm ||
|| repositories                   || http://download.opensuse.org/repositories/home:/dassit/ ||
|| source code                        || source:dasscm/trunk ||

{{{
#!html
<iframe src="http://software.opensuse.org/download/package.iframe?project=home:dasscm&package=dasscm">
here should be an iframe
</iframe>
}}}

= Wording =

It is not always easy to get the context of eg. repository, because it can mean "server side svn repository", "package repository", like "RPM repository" or sometimes also your local svn ckeckout.
To distinguish between the different terms, we try to use the following terms in a consistent way:

|| target system      || the system were dasscm is installed and used ||
|| Subverson server   || the system were your SVN repository is hosted ||
|| system files       || config and other files on your system, like /etc/ntp.conf ||
|| system files managed by dasscm || the part of your system files that has already been checked in to Subversion via dasscm ||
|| local svn checkout             || your local svn checkout on the target system ||
|| svn repository                 || the Subversion repository were the "system files managed by dasscm" are versioned ||
|| package repository             || the installation source repository for dasscm ||



= About =

dasscm is a wrapper Perl script around the {{{svn}}} command. 
If you're planing to check-in your system configuration files into a Subversion repository, {{{dasscm}}} eases your life.

Instead of copying files from the system to the corresponding local subversion checkout directory and commit them there,
you just use:
{{{
dasscm login
dasscm add /etc/ntp.conf
}}}

Missing directories are added automatically.

But the real advantage, compared to plain {{{svn}}} is, that there is the possibility to check, if your local system files have changed against the repository. Just call:
{{{
dasscm status
}}}

For Nagios NRPE integration use
{{{
dasscm check
}}}


{{{
#!graphviz
digraph G {
"dasscm" -> "svn (dasscm)"
"svn (dasscm)" -> "Subversion Server"
"svn (user)" -> "Subversion Server"
}
}}}




== Pre-Requirements ==

  * an existing empty directory in a subversion repository. Normally you create a new directory of every dasscm installation (like http://mysubversionserver/config/HOSTNAME)
  * a user with read permissions to this subversion repository. The username {{{dasscm}}} is a good choice

== Configuration ==

After installing it is required to configure {{{dasscm}}}.
All configuration changes have to be done in the file {{{/etc/dasscm.conf}}}

[[Include(source:dasscm/trunk/etc/dasscm.conf, text/plain)]]

Set the following variables according to your needs:
    || {{{DASSCM_REPOSITORY_NAME=system-name}}}                          || normally {{{hostname -f}}} ||
    || {{{DASSCM_CHECKOUT_USERNAME=dasscm}}}                             || subversion user with read-only permissions ||
    || {{{DASSCM_CHECKOUT_PASSWORD=dasscm-password}}}                    || subversion password for {{{$DASSCM_CHECKOUT_USERNAME}}} || 
    || {{{DASSCM_SVN_REPOSITORY_BASE=http://your-svn-repository/path/}}} || subversion directory in which the {{{$DASSCM_REPOSITORY_NAME}}} directory is located ||
 
If it not already exists, you can create your subversion subdirectory by
{{{
source /etc/dasscm.conf
svn mkdir -m "initial" --no-auth-cache $DASSCM_SVN_REPOSITORY_BASE/$DASSCM_REPOSITORY_NAME
}}}



== Subcommands ==

dasscm suppots following subcommands:
{{{
    add PATH_PROD     
                    add a file to the subversion repository
                    Unlike the native svn command,         
                    dasscm adds and immediatly submits a file to the subversion repository
    blame PATH_REPO                                                                       
                    like "svn blame"                                                      
    check                                                                                 
                    perform Nagios NRPE conform check                                     
    cleanup                                                                               
                    internal, used to clean repository checkout                           
    commit PATH_REPO                                                                      
                    commit a changed file to the subversion repository                    
    complete CMD                                                                          
                    internal, used for bash completion                                    
    complete_path                                                                         
                    internal, used for bash completion                                    
    complete_repopath                                                                     
                    internal, used for bash completion                                    
    diff PATH_REPO
                    display the differences between files on the system and the repository
    help CMD
                    print help and usage information
    init
                    initialize local subversion checkout.
                    This is the first thing to do (after configuring /etc/dasscm.conf)
    login USER
                    user login to Subversion repositoty
    ls PATH_REPO
                    list file from repository
    permissions
                    internal, used to update information about file permissions
    revert PATH_REPO
                    revert local changes back to version from the repository (see diff)
    status PATH_REPO
                    display status information about modified and deleted files.
                    If no path is given "/" is assumed
                    (in contract to "svn" with assumes ".")
    update PATH_REPO
                    update local repository checkout
                    Normally, this is done automatically

}}}


==== login ====

For convinience use 
{{{
dasscm login
}}}

This opens a shell, where the environment is set to the required values.

==== add files/directories ====

For example cups configuration


{{{
# it is recommended to check initially check a file before you first edit it. Use the comment "orig"
dasscm add -m "orig" /etc/sysconfig/cups
# make you changes to /etc/sysconfig/cups
dasscm commit -m "my comment about my change" /etc/sysconfig/cups
}}}

==== checkin modified files ====

{{{
dasscm commit -m "my comment about my change" /etc/sysconfig/cups
}}}

Note: every "add" also calls "commit", so the command "commit" is not really required

==== status ====

{{{
dasscm status
}}}

==== store file permissions ====

on every call of {{{dasscm add/commit}}} als file permissions are evaluated and stored in the file 
{{{
/etc/permissions.d/dasscm.permissions_backup
}}}

==== restore file permissions ====

On SUSE system:
{{{
cp -a /etc/permissions.d/dasscm.permissions_backup /etc/permissions.d/dasscm.permissions
# change all file permissions to the values, that are defined in the file /etc/permissions.d/*.permissions
/sbin/conf.d/SuSEconfig.permissions
}}}


==== diff ====

{{{
dasscm diff $filename
}}}
shows the differences of a local system file against the file in the local svn checkout.

==== revert ====

If a local system file is modified (see {{{dasscm diff}}})
it can be reverted to the checked in version by
{{{
dasscm revert $filename
}}}


==== help ====

for online-help type

{{{
dasscm help
}}}


== dasscm as non-root user ==

Using {{{dasscm}}} as non-root user requires sufficient permissions.

  * create group {{{dasscm}}}. Default GID is 4199
  * {{{chgrp dasscm /etc/dasscm.conf}}}
  * verify group {{{dasscm}}} has read permission on {{{/etc/dasscm.conf}}}

=== why sudo? ===

{{{sudo}}} is required to guarantee that the user has access to all files on the target system.

=== configure dasscm for non-root users ===

{{{
# check if group dasscm is defined (GID 4199 is default)
# The group must contain all users that should use dasscm
getent group dasscm

# read permission on config file
chgrp dasscm /etc/dasscm.conf

# add sudo rule
echo "
Defaults env_keep+=DASSCM_USERNAME
Defaults env_keep+=DASSCM_PASSWORD
dasscm ALL=(ALL) NOPASSWD:/usr/bin/dasscm" >> /etc/sudoers
}}}

Also check, that {{{requiretty}}} is disabled. 
On SUSE, this is the default, on RedHat it requires modifying the /etc/sudoers.



=== usage (non-root) ===

{{{
# login
dasscm login

sudo dasscm status

sudo dasscm ls

sudo dasscm add <DATEINAME>
}}}


== Nagios/NRPE Check ==

Client-side configuration for NRPE.

dasscm comes with config files for nrpe and sudo.
Unfortunally, not all distributions have directories for
{{{/etc/nagios/nrpe.d}}} or {{{/etc/sudoers.d/}}}.

If the distributions does not provide these directories,
dasscm delivers the configs in {{{/usr/share/doc/packages/dasscm/}}}.

In this case, the dasscm configuration must be integrated into the system manually.

When not using the delivered config files at all,
it is still possible, to configure the services purely manually:
{{{
# nrpe config file
CFG=/etc/nagios/nrpe.cfg

# get NRPE user
NRPE_USER=`sed -n 's/nrpe_user=//p' $CFG`
echo "NRPE_USER: $NRPE_USER"


# add NRPE_USER sudo rule for dasscm
grep -q "dasscm check" /etc/sudoers || echo "$NRPE_USER ALL=(ALL) NOPASSWD:/usr/bin/dasscm check" >> /etc/sudoers

# add check_dasscm to NRPE config
grep -q dasscm $CFG || echo "command[check_dasscm]=sudo dasscm check" >> $CFG

# restart nrpe
/etc/init.d/nrpe restart
}}}

It is possible to user the dasscm nrpe check without sudo,
that file without read-permissions will not be checked

= related projects =

  * http://svn.apache.org/viewvc/subversion/trunk/contrib/client-side/asvn
  * http://fsvs.tigris.org/
  * http://joey.kitenet.net/code/etckeeper/