scc(5)




NAME

       scc-srv - introduction SCC-SRV


RELEASE

       scc-srv	 1.7.5


INTRODUCTION

       The complete functionality of the server part of SCC consists of:

       - receive files sent by scc from client systems
       - transfer of these files to the directory used by the web server
       - summarize data in the received files
       - allow search and compare functionality through a web server

       Refer to the manual pages of scc for details concerning the SCC client.


   Summary of activation
       The following list summarizes the steps to  get	scc-srv	 working.   We
       assume that SCC-data is transferred via email and that it is referenced
       by a symbolic link from the document root of the web server.  Refer  to
       the  remainder  of  this	 document for a more detailled description and
       other setups.

       1  activate the web server and email-processing
       2  install scc-srv
       3  extend the mail-alias file:
	     scc-transfer: "| /opt/scc-srv/bin/scc-receive-mail"
       4  activate the new alias:
	     newaliases
       5  determine the user and group used by during the email delivery
	  and assign the proper ownership (assume mail:mail):
	     scc-update -m mail:mail
       5  determine the user of the webserver assign the proper ownership
	  (assume http):
	     scc-update -w http
       6  put the SCC-data in applications/scc under the document root:
	     mkdir <doc-root>/applications
	     ln -s /var/opt/scc-srv/data/www <doc-root>/applications/scc
       7  indicate this path to scc-srv:
	     scc-update -d /applications/scc
       8  schedule scc-update to process incoming SCC-data, frequency depends
	  upon the amount of data and time of arrival of new SCC-data.
	     scc-update	   # no arguments/options required

       It is also possible to pull the scc-files from the clients after remote
       execution.   This avoids steps 3, 4, 5 and the scheduling of scc on the
       clients.	 Refer to the section "Pulling files  from  the	 clients"  for
       more details.


   Installation
       First of all we need a working scc server system.  Later we will need a
       client system to send its data through email, scp, ftp, rcp  or	cp  to
       the  server.  Install version 1.3.23 of the server software with one of
       the following commands:

	  swinstall -s $(pwd)/scc-srv-1.3.23.hpux-1x.depot scc-srv
	  pkgadd -d ./scc-srv-1.3.23.sunos.pkg -a none scc-srv
	  rpm -U ./scc-srv-1.3-23.i386.rpm
	  tar xf ./scc-srv-1.3.23.src.tar; cd scc-srv; ./scc-srv-install
	  pkg_add ./scc-srv-1.3.23.FreeBSD.tgz
	  pkg_add ./scc-srv-1.3.23.NetBSD.tgz
	  pkg_add ./scc-srv-1.3.23-OpenBSD.tgz


       This installs several programs in the directory /opt/scc-srv/bin , man-
       ual  pages in /opt/scc-srv/man and a directory tree under /var/opt/scc-
       srv/data.  To access these programs and manual pages,  you  can	extend
       your PATH and MANPATH variables during the configuration phase.	During
       "normal" operations, direct access and usage of the scc-server software
       is  not required and the following settings are not necessary after the
       completion of the configuration.

	  PATH=${PATH}:/opt/scc-srv/bin
	  MANPATH=${MANPATH}:/opt/scc-srv/man
	  export PATH MANPATH


       When you want to install the software in	 another  directory,  download
       the  source tarball, customize and use the script "relocate" and gener-
       ate the appropriate depot/package/rpm.	The  source  tarball  contains
       scripts to generate several native install formats.

       The following paragraphs describe how the data-directory tree should be
       used to receive and transfer the files to their ultimate location.


   Receiving files
       When the scc client has collected its data,  it	can  send  it  through
       email,  scp,  ftp,  rcp or cp.  The destination of the files depends on
       the communication program:

	  - cp:	 <directory>
	  - ftp: srv.dom:<directory>
	  - scp/rcp:  <user>@srv.dom:<directory>
	  - email:    <user>@srv.dom



   Receiving files using scp/rcp
       Suppose you decide to send data from (some of)  your  systems  to  your
       scc-server  by  means of scp or rcp.  Your steps depend on the way file
       transfer between systems in your network is done at the	moment.	  When
       all or most of your systems use scp of rcp for user root, the necessary
       key-files and rhost-files are  already  in  place.   Each  transfer  on
       behalf of scc from a client can use the existing communication path and
       has to specify the full path of the destination directory.

	  scc -p scp \
	      -s root@srv.dom:/var/opt/scc-srv/data/transfer/cp

       When you use several accounts to transfer files to your server, you can
       create  several	subdirectories	in  /var/opt/scc-srv/data/transfer/cp,
       each owned by a specific user.

       Add the proper key files or rhosts file to the home-directory  of  (for
       example)	 user  scc  to enable communication between the client and the
       server.	Clients can now send the data using the following command:

	  /opt/scc/bin/scc -p scp -s scc@srv.dom:



   Receiving files using ftp
       Suppose you decide to send data from (some of) your systems with ftp to
       your  scc-server.   You	have  to create a ~/.netrc file containing the
       data of the account that receives the SCC-data.	The contents  of  this
       file are:

       machine <scc-srv> login <account> password <password>

       Make sure only root can read this file as it contains a plaintext pass-
       word.  This file can also be used with an anonymous ftp-server.	It  is
       obvious	that  you should not use the root-account of the scc-server in
       this file.  Use a separate account as described with the transfer using
       scp/rcp.


   Receiving files using email
       Suppose you decide to send data from (some of) your systems by email to
       your scc-server.	 We have to extend the alias file  on  the  scc-server
       with  an	 alias that triggers a program that puts the email contents in
       the proper directory.  This program is scc-receive-mail(1).  So, extend
       your aliases file with:

	  scc-transfer:	   "| /opt/scc-srv/bin/scc-receive-mail"

       The   default   destination   directory	 of   scc-receive-mail(1)   is
       /var/opt/scc-srv/data/transfer/mail.  Another directory can  be	speci-
       fied  as	 an  argument  for  scc-receive-mail(1).  Do not forget to run
       newaliases to activate the new alias.

       To reduce the likelihood of DOS-attacks, you should use	a  non-obvious
       email-alias and not the alias from this documentation.

       We  have to consider the following security aspects of programs invoked
       through an email alias.	The program scc-receive-mail(1) runs under the
       uid/gid	specified  by the mail-handler.	 On a vanilla RH7.3 with send-
       mail, this is mail/mail.	 The destination directory should be  writable
       for this user.  The rpm for scc-srv sets the uid:gid for this directory
       to root:root.  To change this, use the -m option of scc-update(1).

	  scc-update -m mail:mail

       Subsequent calls of scc-update(1) do not need to specify this option.

       On some systems the smrsh option (sendmail restricted shell)  is	 acti-
       vated.	This  means  that  only	 programs  located  in	the  directory
       /etc/smrsh can be activated through an email alias.  When you keep  the
       smrsh  option,  you  have  to  add  some	 additional  programs  to this
       restricted shell environment:

	  cd /etc/smrsh
	  ln -s /opt/scc-srv/bin/scc-receive-mail scc-receive-mail
	  ln -s /bin/cat cat

       Modify the file sendmail.mc to alter this  option.   The	 program  scc-
       receive-mail(1)	is not complicated and only uses the program /bin/cat.
       Now clients can send their data to the scc-server  with	the  following
       command:

	  scc -s scc-transfer@srv.dom

       When  you use another mail-handler, like postfix, all you need to do is
       to determine the user:group that is used to run scc-receive-mail(1) and
       change the ownership for the transfer-directory with the -m option.


   Receiving files using cp
       The destination has to be a directory on the client (and server).  This
       option can be used on the server.


   Pulling files from the clients
       In the case of password-less ssh/rsh communication from your server  to
       clients,	 it  is	 also possible to pull the scc-files from the clients.
       Use scc-pull(1) to start scc on the  clients  and  pull	the  resulting
       files  to the server.  The program supports several options controlling
       the execution on the clients.  It  also	supports  several  options  to
       specify from which clients to pull the scc-files.  In it simplest form,
       the program can be called without any options.  In that	case,  scc  is
       executed in the background on all systems whose snapshot resides in the
       realm All.  After waiting for 10 minutes, the scc-files	are  retrieved
       from all clients and scc-update is called to update the website.

       After installing scc on a new client, the system has to be added to the
       command-line of scc-pull.  When scc-pull uses the -R option, it has  to
       be called manually once with the -S option to let the files become part
       of realm All.  Possibly you have to use scc-realm(1)  to	 add  the  new
       system to the required realm.  Now the scc-files of <sys> reside in the
       required realm and subsequent calls of scc-pull will access the system.
       Before  using  scc-pull for a new system, you should test the password-
       less communication from the scc-srv to the new system.


   Transfer of data to web server
       The data, that is sent by the scc-clients, ends up in directories  "cp"
       and  "mail" under /var/opt/scc-srv/data/transfer.  The files are packed
       by tar and compressed by gzip or compress.  Data sent by email is  also
       uuencoded.  The command scc-transfer(1) unpacks the data into files and
       transfers  them	to  the	 directory  /var/opt/scc-srv/data/www/All  and
       assigns	the  proper  permissions  and ownership.  It is called by scc-
       update(1).

       The web server has to read the files.  Therefore we have to change  the
       ownership  of the files to the user that is used to run the web server.
       Use the -w option of scc-update(1)  to  change  the  ownership  of  the
       directories and files.

	  scc-update -w apache

       Subsequent  calls  of scc-update(1) do not need to specify this option.
       Now all html-files, snapshots, log files and summaries are  present  in
       the directory /var/opt/scc-srv/data/www/All.

       The  summaries  of  the	runs  on the clients are generated by scc-sum-
       mary(1).	 The specification of the System Tools (required by scc-smt(1)
       is  done	 by editing the file /var/opt/scc-srv/data/www/All/custom/scc-
       smt-select Refer to the manual page of  scc-smt(1)  for	more  details.
       The  specification of the rules for scc-rules(1) is done by editing the
       file /var/opt/scc-srv/data/www/All/custom/scc-rules.conf Refer  to  the
       manual  page  of scc-rules(1) for more details.	The three programs are
       called by scc-update(1).

       Add scc-update(1) to the root-crontab.  The time and  frequency	depend
       upon the time and frequency you use for running SCC on the clients.


   Performance considerations
       Testing	scc-update with many snapshots, it appears that scc-rules con-
       sumes some 40% of the  time  scc-update	requires.   When  you  do  not
       require	the  checks  of	 the  rules,  remove  the  configuration  file
       /var/opt/scc-srv/data/www/All/custom/scc-rules.conf to  speed  up  scc-
       update.

       The  programs  have  been tested with 100, 1000 and 2000 snapshots.  In
       that range, there is a linear dependency between the required time  and
       the number of systems.


   Display of SCC-data by the web server
       You have to decide whether you put the SCC-data under the document-root
       or link from the document-root to the SCC-data.	In the first case, use
       the commands:

	  mkdir <doc-root>/applications
	  mv /var/opt/scc-srv/data/www <doc-root>/applications/scc
	  ln -s <doc-root>/applications/scc /var/opt/scc-srv/data/www

       In the latter case, use the commands:

	  mkdir <doc-root>/applications
	  ln -s /var/opt/scc-srv/data/www <doc-root>/applications/scc


       To  display  the	 SCC-data  by the web server, you have to indicate the
       path from the web-server document-root to the SCC  web-root.   Use  the
       following command to achieve this:

	  scc-update -d "/applications/scc"

       Note  the  leading  "/" for the argument of the -d option.  In the Unix
       filesystem hierarchy, applications/scc is a relative path.  For the web
       server, it is an absolute path under the document-root.

       When  you  relocate  the	 SCC-data  (or	the  document-root  of the web
       server), you have to use the -d option again.  Without relocation, sub-
       sequent	calls  of  scc-update(1) do not need to specify the -d option.
       When  the  web  server  displays	 only  the  SCC-data,  you   can   use
       /var/opt/scc-srv/data/www  as  the document-root of the web server.  In
       that case, you do not need to use the -d option for scc-update(1).

       To restrict the access  to  the	SCC-data  in  directory	 /var/opt/scc-
       srv/data/www/All, you can use an .htaccess file in this directory.

       Access  to  the	data  is  achieved  by a cgi-script, called by the web
       server.	This script, scc-wrapper.cgi(1) is located in the cgi-bin sub-
       directory  of  /var/opt/scc-srv/data/www/All  The images, shown in some
       pages, are located in the subdirectory custom.

       Record the following settings in a separate file in the	conf.d	subdi-
       rectory of Apache 2.x when /var/www/html is the directory of your docu-
       ment-root:

	  <Directory "/var/www/html/applications/scc">
	    Options -Indexes FollowSymLinks +ExecCGI -Includes
	    AllowOverride AuthConfig
	    Order allow,deny
	    Allow from all
	  </Directory>

	  ScriptAliasMatch  "^.*/([^/]*)/cgi-bin/scc-wrapper.cgi" \
	    "/var/opt/scc-srv/data/www/$1/cgi-bin/scc-wrapper.cgi"


       For Apache 1.x, the ScriptAliasMatch has to be replaced with:

	  ScriptAlias prefix/All/cgi-bin/scc-wrapper.cgi \
	    /var/opt/scc-srv/data/www/All/cgi-bin/scc-wrapper.cgi
       Where prefix has to be replaced by the  path  under  the	 documentroot.
       This value is also supplied with the -d option of scc-summary(1).  This
       line has to be repeated for each realm you create.

       To save space, the SCC-data of a system in a realm consists of symbolic
       links  to  the realm All.  When you use only one realm ( All ), you can
       do without the option FollowSymLinks in the configuration-file  of  the
       web server.


       Be  sure	 to  stop  and	start the web server to activate the settings.
       Note that this setting is incompatible with scc-srv release 1.5.16  and
       earlier.


   AUTHORISATION
       When  it	 is  not  desirable that all administrators have access to the
       SCC-data of all your systems, you can create additional sub-directories
       in  /var/opt/scc-srv/data/www  These sub-directories are called realms.
       Realms are maintained by means of scc-realm(1).	This program  supports
       the creation of a realm and adding/deleting systems to/from a realm.

       To  create  a  new realm Education and add the systems c012 and c014 to
       this realm, use the following command:


	  scc-realm -a c012,c014 -c Education

       To update the summaries for this realm, scc-update(1) is	 called	 after
       creating	 the  directory	 and the links for the SCC-data.  Refer to the
       manual page for more detailed description  of  setting  up  realms  and
       their permissions.

       It  is  possible	 to populate realms automatically by means of the file
       scc-auto-realm.conf in the custom subdirectory of a  realm.   Based  on
       hostname, OS and domain systems are (de)selected for a realm.  The sys-
       tems in the All realm are the base for this  process.   Refer  to  scc-
       update(1) for more details.

       You  have  to edit the file Education/.htaccess to restrict access to a
       realm.

       When you followed all the steps mentioned before in this document,  you
       should  be  able to see the start-page of SCC.  Use the path you speci-
       fied with the -d option of  scc-update(1)  in  your  favorite  browser.
       This start-page allows access to the realm All and to the documentation
       of scc-srv.  Note that new realms that are  created  with  scc-realm(1)
       are  added  automatically  added to this page when a specific marker is
       preserved in the file index.html.

       You are now ready to run a scc-client and transfer data to the  server.
       Choose  a  client-system	 and  a transfer-option and run scc.  Then run
       scc-update(1) on the server to transfer the data to the web-server  and
       to generate summaries.  When all the above steps have been followed, no
       options need to be specified.


   SECURITY
       The server receives SCC-data from clients by email, scp,	 ftp,  rcp  or
       cp.   A Denial Of Service is possible by frequently sending large snap-
       shots of fake  hosts  to	 the  SCC  server.   Furthermore,  anyone  can
       (re)send	 SCC-data  from	 any system to the SCC server.	Therefore, the
       SCC server should only be deployed in a trusted network.

       When the client sends its data using email via the internet, the sensi-
       tive  data  should be encrypted.	 This is achieved by generating a pair
       of public/private keys on the server.  The clients encrypt the SCC-data
       using DES3 with random pass phrase.  The pass phrase is encrypted using
       RSA with the public key	of  the	 server.   The	server	receives  both
       encrypted  files	 and  uses  its	 private key to obtain the random pass
       phrase used by the client.   Finally,  this  pass  phrase  is  used  to
       decrypt the SCC-data.  To generate the keys on the server, use the fol-
       lowing commands:

	  # cd /var/opt/scc-srv
	  # umask 077
	  # mkdir encryption
	  # cd encryption
	  # openssl genrsa -out private_key 2048
	  Generating RSA private key, 2048 bit long modulus
	  .................+++
	  .........................................................+++
	  e is 65537 (0x10001)
	  # openssl rsa -in private_key -out public_key -pubout
	  read RSA key
	  writing RSA key
	  # ls -l
	  total 16
	  -rw-------	1 root	   sys	     1679 Sep 29 08:51 private_key
	  -rw-------	1 root	   sys	      451 Sep 29 08:52 public_key


       The file public_key should be transferred to the SCC-client.  The  path
       of  the	file  private_key  should  be  added to the file /var/opt/scc-
       srv/conf/scc.conf with the following keyword:

       SCC_PRIV_HOST_KEY=/var/opt/scc-srv/encryption/private_key


       After  transferring  the	  public   key	 to   the   client   in	  file
       /var/opt/scc/encryption/public_key  the	data can be encrypted and sent
       with the command:

       /opt/scc/bin/scc			       \
	    -k /var/opt/scc/data/encryption/public_key	 \
	    -s scc-transfer@srv.dom


       When the client cannot use a mail-client, use the -i and -p options  to
       send  the  data	via  SMTP.   Refer  to the manual page of scc for more
       details.


   TROUBLESHOOTING
       First of all, check the URL you are using to display  the  data.	  This
       should correspond with the path you specified (once) with the -d option
       of scc-update(1).

       When the data of a scc-client does not  show  up,  you  can  check  the
       directories  under  /var/opt/scc-srv/data/transfer whether the raw data
       arrived.	 Also check any possible errors reported by the	 clients  when
       sending	the  data.   scc-transfer(1)  logs  its	 actions when the file
       /var/opt/scc-srv/data/log/scc-transfer.log exists.   Create  this  file
       and try to send the data again.

       The  log	 files of the web server can also be checked.  When the start-
       page of SCC and the start-page of the realm All show up, but  the  cgi-
       script  does  not  function  correctly,	check  the  file /var/opt/scc-
       srv/data/log/scc.cgi.log.  scc.cgi(1) logs its  actions	in  this  file
       when  it	 exists	 and  is  writable by the user running the web-server.
       Create this file and try to access the URL again.

       A restrictive selinux can also avoid the display	 of  SCC-data.	 Check
       the  appropriate	 logfile  to  find  out whether selinux is causing the
       problems.

       When this does not give any clues, you can  edit	 the  cgi-scripts  and
       trace  their  execution.	  Add  the following to the start of scc-wrap-
       per.cgi or scc.cgi:

	  exec 2>/tmp/scc-log
	  set -x

       On abnormal termination of a run of a scc-client, the snapshot will not
       be  complete and the next run will produce huge differences.  To remove
       these differences, you have to edit the log file on the client.


   DEPENDENCIES
       The clients of SCC try to use gzip or compress to reduce the amount  of
       data  sent to the server.  This means that the server has to be able to
       access both gunzip and uncompress.  To install  uncompress  on  RedHat,
       install ncompress.

       The  SCC-data  that  is	sent by email, is uuencoded.  The server needs
       uudecode.  To install uudecode on RedHat, install shar-utils.


PROGRAMS AND FILES

       The programs of scc-srv have the following relationship:

       - scc-receive-mail: move SCC-data to transfer-area
	 activated by /etc/aliases
       - scc-update: main update of data on website
	 activated by cron, this program calls:
	    - scc-transfer: move data from transfer-area to website
	    - for each realm:
		 - scc-rules: check rules
		 - scc-summary: update general summaries
		 - scc-smt: generate summary of System Tools
       - scc-pull: run scc on clients and pull files to server
	 this program calls:
	    - scc-update
       - scc-wrapper.cgi: wrapper for web-interface
	 activated by user, this program calls:
	    - scc.cgi: handle web-interface
		 - search/show summaries/log
		 - scc-syscmp: compare parts of snapshots
		      - scc-baseline: extract part of snapshot

       The HTML-files have the following relationship:

       - scc-help/scc*.html: help-files for the userinterface of scc-srv
	 part of distribution
       - scc-help/scc-srv/scc*.html: manual pages for scc-srv
	 part of distribution
       - scc-help/scc/scc*.html: manual pages for scc client
	 part of distribution
       - scc-help/scc-win/scc*.html: manual pages for scc-win
	 part of distribution
       - index.html: main-menu to realms
	 part of distribution, contains a specific line to assist scc-realm(1)
       - All: directory of main realm
	 part of distribution
	    - index.html: interface to snapshots/log files and summaries
	      calls scc-wrapper.cgi to perform action and display data
	      generated by scc-summary
		 - scc-summary-<cat>: summary of snapshots sorted on <cat>
		   supported categories are:
		      - host
		      - OS
		      - model
		      - last run/change
		   generated by scc-summary
		      - scc.<host>.html: snapshot of <host>
		      - scc.<host>.log.html: logbook of <host>
			transported by scc-transfer
		 - scc-log-index.html: summary of changes per day
		   generated by scc-summary
		      - scc-log-<date>.html: summary of systems with changes on <date>
			generated by scc-summary
			   - scc.<host>.log.html: logbook of <host>
			     transported by scc-transfer
		 - scc-rules-index.html: summary of messages
		   generated by scc-rules
		 - scc-smt-index.html: summary of System Tools
		   generated by scc-smt
		      - scc.<host>.smt.html: System Tools for <host>
			generated by scc-smt
		 - dynamic data with results of searching
		   generated by scc.cgi (called by scc-wrapper.cgi)
		      - scc.<host>.html: snapshot of <host>
		      - scc.<host>.log.html: logbook of <host>
			transported by scc-transfer
		 - dynamic data with results of comparing snapshots
		   generated by scc.cgi (called by scc-wrapper.cgi)


CLASS

       A class-file contains lines with (parts of) classifications.  When they
       are not present, colons are added in front and at the end of each clas-
       sification.  Lines starting with '#' are treated as comments.

       To extract the boot configuration and start/stop links out a  snapshot,
       use the following class-file:

	  boot:config:
	  boot:rc-file:

       Class-files  are	 used  by scc-baseline(1) and scc-syscmp(1). Check the
       snapshots to determine the classifications to be extracted.


COPYRIGHT

       SCC is free software under the terms of the GNU General Public License.
       Copyright (C) 2001-2004 Open Challenge B.V., 2004-2005 OpenEyeT Profes-
       sional Services, 2005-2009 QNH.


SEE ALSO

       scc-baseline(1), scc-pull(1), scc-realm(1), scc-receive-mail(1), scc-rules(1),
       scc-smt(1), scc-summary(1), scc-syscmp(1), scc-transfer(1), scc-update(1),
       scc-wrapper.cgi(1), scc.cgi(1), scc-srv(5)


VERSION

       $Revision: 1.49 $