Likewise Open Files

README for Likewise Open Agent (Server components)
Revision 0.12.1, January 25, 2006

*as always, post feedback on the likewiseopenagt forum(s) on Sourceforge.net*

------------------------------------------------------------------------------
INTRODUCTION
------------------------------------------------------------------------------

Likewise Open Agent helps to bridge the gap between the excellent open source
projects like Samba (file and print serving) and management of those packages
and servers by Microsoft(R) Windows(R) clients. 

This development release supports using the Windows Microsoft Management Console 
(MMC) to perform the following administration task on Linux(R) servers:
-> Add/delete/modify file shares
-> Add/delete/modify print shares
-> Use the Device Manager plug-in to view the properties of a Linux system
-> Right-click on a Linux server to view properties and/or shut down the machine
-> Collect events from the Linux system for display through the Microsoft Event 
Viewer
-> Using Samba 3.0.21 or later, provide performance counter information through 
the perfmon client application

Components of the Likewise Open Agent include:
-> Client-side components work in conjunction with MMC (part of the Windows 
operating systems since 2000). The client communicates to the Linux server using 
the RPC mechanism built into Windows, or SOAP.
-> On the server, Samba (http://www.samba.org) services Microsoft RPC-related 
traffic, while Web services are used to handle some support services through SOAP.

About the Server
----------------
Likewise Open Agent works in conjunction with Samba, CUPS and other Linux 
applications. Many management functions utilize Samba and its RPC mechanisms and 
callouts. Functionality not supported by Microsoft RPC and Samba is provided 
through SOAP services calls to a server hosted using SOAP-Lite.

In the initial release, the SOAP server doesn't include 
authentication components since the only web services that are provided
are 'get' type of operations. Care should be taken if other functionality is 
programmed without authentication components.

Java was used to write the helper applications providing the functionality expected
by Samba's various "callouts." An example smb.conf file is provided in 
Linux/SambaScripts. For more information on the callouts, see John Terpstra's 
book, The Official Samba-3 HOWTO and Reference Guide, or see the documentation 
at http://www.samba.org.

------------------------------------------------------------------------------
BUILDING AND INSTALLING
------------------------------------------------------------------------------

First you'll need to download source code from 
http://sourceforge.net/project/likewiseopenagt. Download the code to the 
location where you will build it - there are two branches to the tree, one for 
Linux and one for Windows. The Windows code compiles on the Windows platform, 
and the Linux code compiles on Linux.  

The source code directories provide the following: 
-> cesm-agent -- Code related to the Jetty server components 
docs; information that might be useful to the project
-> EventLogDB -- Facility to harvest lines from various log files and convert 
them into eventlog records
-> HWInfoFilter -- Supports the "device manager" functionality from the server 
perspective
-> SambaScripts -- Callouts from smb.conf for starting or stopping the shutdown 
sequence

Install Dependencies, Tools and Server Components
-------------------------------------------------
To build the server-side components, you will need the following tools and 
packages. Install them in locations that are convenient to you, and then update 
entries in cesm-agent/build.properties. Note that properties ending in "dir"
indicate that they point at directories, while those that don't point at
particular files (e.g. log4j should reference the file log4j.jar).

*** New in 0.12 -- dependency on SOAP::Lite.
The SOAP services are supplied by the SOAP::Lite module, available in many 
distributions, as well as from www.soaplite.com. Version 0.66 fixes a known 
incompatibility with Microsoft .NET runtime, and is required. If your distribution
doesn't have version 0.66, you can get it from www.soaplite.com.

Make sure that you have version 3.0.21 or later of Samba (from www.samba.org). 
Prebuilt binary packages for many distributions are available from that Web 
site, or you can build your own for your specific platform. If you're going to 
compile it yourself, pay close attention to dependencies such as Kerberos, 
attributed file systems such as xfs, and the compile-time attributes. Most 
important is to compile with ACL support, using a system that supports ACL file 
systems. Compiling Samba is beyond the scope of this document -- refer to the 
documentation at www.samba.org for more information.

Note that if you'll be compiling HWInfo or Samba, you'll need a C/C++ compiler 
(such as GCC). 

TOOLS:
-> Java SDK - from java.sun.com. Version 1.4.2 has been tested with this release.
-> SOAP-Lite - from cpan.org, or included in most Linux distributions
-> Apache Ant (ant.apache.org) -- Used to manage build configuration (in lieu of 
other tools like make). 

***Don't forget to set the JAVAHOME environment variable to point to the J2SE 
bin directory.***

PACKAGES:
-> log4j (http://logging.apache.org/log4j) -- Download this and do 'ant dist' to 
build the jar. Adjust the path in the build properties to the location of the 
jar.
-> concurrent (EDU.oswego.cs.dl.util.concurrent --
http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html) 
-- You'll need to build concurrent into a jar file using the build.xml file 
provided with the release.
-> HWInfo (various places on the Internet, but also in the vendor-source 
directory) - Used to feed information to the Device Manager. If your 
distribution doesn't already have it, you'll need to compile it and make sure 
it's in /usr/sbin/hwinfo. 

Running the Web Services Components during development
------------------------------------------------------
Replace <likewiseDevelopmentDir/Linux> with the actual location of the Likewise 
Open Agent development files. This will enable you to make development changes 
and immediately test them after restarting Samba. 

-> To deploy various files in the right locations, and modify smb.conf,
type 'ant deploy' *** in the Linux directory **

-> To verify that the Web service has been compiled correctly, type ant 
runonly, which will run likewise-open-agent.pl SOAP server.

-> To verify that likewise-open-agent SOAP server is running, use one of 
the test scripts located in the cesm-agent/test/scripts directory to 
access your server. getDeviceTree.pl is especially useful, since it also
verifies that hwinfo_filter.pl is set up correctly in the right location.

------------------------------------------------------------------------------
BUILDING AN RPM FOR SERVER INSTALLS
------------------------------------------------------------------------------
-> To (optionally) build an RPM that can be used to install the server
components on OpenSuSE systems, in the Linux directory type "ant rpmbuild"

-> See the section below on using this RPM.

------------------------------------------------------------------------------
CONFIGURING SAMBA
------------------------------------------------------------------------------

Now, make sure that a recent version of Samba is configured correctly for your 
system. Build your own, or get a binary version from www.samba.org.

Choose the best authentication method for your network configuration, and make 
sure that it's working. Note that if you're using server security,
the smbpasswd command should be used to add Samba enabled users. For 
additional authentication setup, see one of the many great references on
configuration and operation of Samba.  

*** Note that each user on the Linux machine will also need to be made a
    'samba user' using the smbpasswd command when using user security mode.
    For example, on initial install, 
    the 'root' user will NOT have the ability to access samba unless added
    explicitly with the 'smbpasswd -a root' command. See the appropriate samba
    documentation for more information in this regard.

Make sure you add appropriate administrator users to the admin users = line in 
the [Global] section of the smb.conf file. 


In Samba 3.0.20 and later releases, eventlogs and performance counters are 
enabled. To use performance counters, specify the following in the [Global] 
section of your smb.conf file:

	eventlog list = Application Security System SyslogLinux

Enable Shutdown
---------------
To enable shutdown API functionality (accessible through the Properties page of 
the client MMC plug-in when focused on a specific server), insert the following 
into the [Global] section of your smb.conf file:

	shutdown script = <likewiseDevelopmentDir/Linux/SambaScripts/>shutdown %t 
%z %x %m %r

Ease Configuration of File/Print
--------------------------------
To enable easy configuration of file and print shares from the MMC console 
client application, make sure you have the following in your smb.conf file:
	
	[c$]
	    create mask = 0664
	    read only = no
	    directory mask = 0775
	    write list = root
	    comment = Likewise  System Root
	    # change the following path to suit your system
	    path = /opt/likewise


*** NOTE THAT THE FOLLOWING STEPS are automated by using the shell script

    /opt/likewise/cesm-agent/bin/postinstall.sh initLikewise WORKGROUP

    (the other steps mentioned above will be added to this step in subsequent
    releases)

Enable Use of MMC
-----------------
To enable the use of the MMC client application to easily add/delete/rename file 
and print shares, add the following to the [Global] section of your smb.conf 
file:

	add share command = /opt/likewise/cesm-agent/sambaShare add
	change share command = /opt/likewise/cesm-agent/sambaShare change
    	delete share command = /opt/likewise/cesm-agent/sambaShare delete
	deleteprinter command = /opt/likewise/cesm-agent/sambaPrint delete /etc/samba/smb.conf
	enumports command = /opt/likewise/cesm-agent/sambaPrint enumports


------------------------------------------------------------------------------
OTHER SETUP
------------------------------------------------------------------------------

-> If HWInfo is not installed, compile and install it.

-> Copy the <likewiseDevelopmentDir>/HWInfoFilter/hwinfo_filter.pl program to 
the /opt/likewise/bin directory - it will be called by one of the Web services 
of cesm-agent.

-> Copy the
<likewiseDevelopmentDir/Linux/SambaScripts/>EventlogDB/evtsyslog.pl and centeris.com-evtlogd
programs to /opt/likewise/bin.  Make an /opt/likewise/bin/Centeris directory, and 
place the EventLogs.pm file in that directory. Start the eventlog collector 
program by typing:

/opt/likewise/bin/centeris.com-evtlogd start

This shell script is typically placed in the /etc/init.d directory, and it 
starts up the evtsyslog.pl program. Note that Eventlogs.pm Perl library must be 
put in the Centeris subdirectory (beneath the directory containing 
evtsyslog.pl).



------------------------------------------------------------------------------
USING THE RPM VERSION OF THE SERVER SOFTWARE
------------------------------------------------------------------------------
If you've obtained or built the RPM for use on (Open)SuSE systems, you can
deploy it to systems that don't have the development environment set up.

Once the rpm is installed, the system can be configured by typing (as root or
with root privileges):

      /opt/likewise/bin/postinstall.sh initLikewise WORKGROUP
  
This will install the appropriate scripts and programs in the correct
directories, configure CUPS printing, set the likewise agent to start on system
boot, make sure that the appropriate ports are open for management through the
firewall, and start the agent. Note that it will NOT enable the shutdown
feature, event logs, or performance counters.