Author: challngr
Date: Thu Jun 27 17:06:28 2013
New Revision: 1497449
URL: http://svn.apache.org/r1497449
Log:
UIMA-2682 Documentation updates.
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part1/overview.tex
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-uguide.tex
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-properties.tex
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-ws-security.tex
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/install.tex
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part1/overview.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part1/overview.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part1/overview.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part1/overview.tex
Thu Jun 27 17:06:28 2013
@@ -184,7 +184,12 @@
\item[Job Lifetime Management and Orchestration] DUCC includes an
Orchestrator to manage the
lifetimes of all entities in the system.
-
+
+ \item[Node Sharing] DUCC allocates processes from one or more users on
a node, each with a specified
+ amount of memory. DUCC's preferred mechanism for constraining
memory use is Linux
+ Control Groups, or CGroups. For nodes that do not suport CGroups,
DUCC agents monitor
+ RAM use and kill processes that exceed their share size by a
settable fudge factor.
+
\item[DUCC Agents] DUCC Agents manage each node's local resources and
all
processes started by DUCC. Each node in a cluster has exactly one
Agent. The Agent
\begin{itemize}
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex
Thu Jun 27 17:06:28 2013
@@ -72,6 +72,14 @@
information until it is {\em unregistered}. Once registered, a service
may be
started, stopped, etc.
+ The {\em register} options are logically divided into two classes:
+ \begin{enumerate}
+ \item ``Meta'' options which define how the Service Manager manages
the service, and
+ \item Options which describe the service itself. These optinos are
analagous to
+ those used to submit a job.
+ \end{enumerate}
+
+ The ``meta'' options include:
\begin{description}
\item[$--$register {[specification file] [options]}] The
specification file is optional. If
specified, it has the same contents as described for the
\hyperref[sec:cli.service-submit]{{\em
@@ -83,11 +91,216 @@
\item[$--$instances {[n]}] This specifies the number of instances
to start when the service
is started. If not specified, the default is 1.
-
- \item[Other keywords] These are the same as described for
\hyperref[sec:cli.service-submit]{{\em
- ducc\_service\_submit}}
+
\end{description}
+ The options describing the service include:
+ \begin{description}
+
+ \item[$--$classpath] The CLASSPATH used for the service, if the
service is a
+ \hyperref[sec:services.types]{UIMA-AS services}. If not specified,
the CLASSPATH used
+ by the {\em ducc\_service\_submit} command is used.
+
+ \item[$--$classpath\_order {[UserBeforeDucc | DuccBeforeUser]} ] When
DUCC deploys a process,
+ set the user-supplied classpath before DUCC-supplied classpath, or
the reverse. This is
+ only valid for \hyperref[sec:services.types]{UIMA-AS services}.
+
+ \item[$--$debug ]
+ Enable debugging messages. This is primarily for debugging DUCC
itself.
+
+ \item[$--$description {[text]}] The text is any quoted string used to
describe the job. It is
+ displayed in the Web Server.
+
+ Note: When used as a CLI option, the description string must usually
be quoted to protect
+ it from the shell.
+
+ \item[$--$environment {[env vars]}] Blank-delimited list of
environment variable
+ assignments for the service. Example:
+ \begin{verbatim}
+--environment TERM=xterm DISPLAY=:1.0
+ \end{verbatim}
+
+ Additional entries may be copied from the user's environment based
on the setting of
+ ducc.submit.environment.propagated in the global DUCC configuration
ducc.properties.
+
+ Note: When used as a CLI option, the environment string must usually
be
+ quoted to protect it from the shell.
+
+ \item[$--$help ] This prints the usage text to the console.
+
+ \item[$--$jvm {[path-to-java]}] This specifies the JVM to use for
+ \hyperref[sec:services.types]{UIMA-AS services}. If not
+ specified, the same JVM used by the Agents is used.
+
+ Note: The path must be the full path the the Java executable (not
+ simply the JAVA\_HOME environment variable.). Example:
+\begin{verbatim}
+--jvm /share/jdk1.6/bin/java
+\end{verbatim}
+
+
+ \item[$--$jvm\_args {[list]} ]
+ This specifes extra JVM arguments to be provided to the server
process for
+ \hyperref[sec:services.types]{UIMA-AS services}. It is a blank
delimited
+ list of strings. Example:
+\begin{verbatim}
+--jvm_args -Xmx100M -Xms50M
+\end{verbatim}
+
+ Note: When used as a CLI option, the argument string must usually be
quoted to protect
+ it from the shell.
+
+ \item[$--$log\_directory {[path-to-log directory]}] This specifies
the path to the directory for
+ the individual service instance logs. If not specified, the
default is \$HOME/ducc/logs. Example:
+\begin{verbatim}
+--log_directory /home/bob
+\end{verbatim}
+
+ Within this directory DUCC creates a subdirectory for each job, using
the numerical
+ ID of the job. The format of the generated log file names as described
+ \hyperref[chap:job-logs]{here}.
+
+ Note: Note that $--$log\_directory specifies only the path to a
directory where
+ logs are to be stored. In order to manage multiple processes running
in multiple
+ machines DUCC, sub-directory and file names are generated by DUCC and
may
+ not be directly specified.
+
+ \item[$--$process\_DD {[DD descriptor]}]
+ This specifies the UIMA Deployment Descriptor for
\hyperref[sec:services.types]{UIMA-AS services}.
+
+ \item[$--$process\_executable {[program-name]}] For
\hyperref[sec:services.types]{CUSTOM
+ services}, this specifies the full path of the program to execute.
+
+ \item[$--$process\_executable\_args {[list-of-arguments]}] For
\hyperref[sec:services.types]{CUSTOM
+ services}, this specifies the program arguments, if any.
+
+ \item[$--$process\_failures\_limit {[integer]}]
+ This specifies the maximum number of consecutive individual service
instance failures that are to be
+ tolerated before stopping the service. The default is five (5). If the
instance is successfully
+ restarted, the count is reset to zero (0), so that the occasional
process failure does not cause
+ the entire service to be terminated.
+
+ \item[$--$process\_memory\_size {[size]}] This specifies the maximum
amount of RAM in GB to be
+ allocated to each Job Process. This value is used by the Resource
Manager to allocate
+ resources.
+
+ \item[$--$scheduling\_class {[classname]}] This specifies the name of
the scheuling class the RM
+ will use to determine the resource allocation for each process. The
names of the classes are
+ installation dependent. If not specified, the default is taken from
the global DUCC
+ configuration \hyperref[sec:ducc.properties]{ducc.properties.}
+
+ \item[$--$service\_dependency{[list]}] This specifies a comma-delimited
list of services the job
+ processes are dependent upon. Service dependencies are discussed in
detail
+ \hyperref[sec:service.endpoints]{here}. Example:
+\begin{verbatim}
+--service_dependency UIMA-AS:RandomSleepAE:tcp:bluej682:61616
UIMA-AS:OtherEp:tcp:bluej123:123
+\end{verbatim}
+
+ Note: When used as a CLI option, the list must usually be
+ quoted to protect it from the shell.
+
+
+ \item[$--$service\_linger {[seconds]}] This is the time in milliseconds
to wait after the last
+ referring job or service exits before stopping a non-autostarted
service.
+
+ \item[$--$service\_ping\_arguments {[argument-string]}] This is any
arbitrary string
+ that is passed to the {\em init()} method of the service pinger. The
contents of
+ the string is entirely a function of the specifici service. If not
specified,
+ a {\em null} is passed in.
+
+ Note: When used as a CLI option, the string must usually be
+ quoted to protect it from the shell, if it contains blanks.
+
+ The build-in default UIMA-AS pinger supports an argument string of the
following form
+ (with NO embedded blanks):
+\begin{verbatim}
+ queue_threshold=nn,window=mm,broker_jmx_port=pppp,meta_timeout=tttt
+\end{verbatim}
+
+ The keywords in the string have the following meaning:
+ \begin{description}
+ \item[queue\_threshold=nn] If the depth of the ActiveMq Queue for
the service exceeds
+ this value for some period of time, the health of the service is
marked ``poor''.
+ If omitted, the value is 0, and no quality measurement is made.
+ \item[window=ww] This defines a ``window'' over which the queue
threshold is measured.
+ the value is the number of consecutive measurements over which the
queue depth must
+ exceed the threshold. If omitted, the window size is 0.
+ \item[broker\_jmx\_port=pppp] This is the JMX port for the service's
broker. If not
+ specified, the default of 1099 is used. This is used to gather
ActiveMq statistics
+ for the service.
+ \item[meta\_timeout=tttt] This is the time, in milliseconds, to wait
for a response
+ to UIMA-AS {\em get-meta}. If not specified, the default is 5000
milliseconds.
+ \end{description}
+
+ \item[$--$service\_ping\_class {[classname]}] This is the Java class
used to ping a service.
+
+ This parameter is required for CUSTOM services.
+
+ This parameter may be specified for UIMA-AS services; however, DUCC
supplies a default
+ pinger for UIMA-AS services.
+
+ \item[$--$service\_ping\_classpath {[classpath]}] If {\em
service\_ping\_class} is specified,
+ this is the classpath containing service\_custom\_ping class and
dependencies. If not
+ specified, the Agent's classpath is used (which will generally be
incorrect.)
+
+ \item[$--$service\_ping\_dolog {[boolean]}] If specified, write pinger
stdout and stderr
+ messages to a log, else suppress the log. See
\hyperref[sec:service.pingers]{Service Pingers}
+ for details.
+
+ \item[$--$service\_ping\_jvm\_args {[java-system-property-assignments]}]
If
+ {\em service\_ping\_class} is specified, these are the arguments
+ to pass to jvm when running the pinger. The arguments are specified as
a blank-delimited
+ list of string. Example:
+\begin{verbatim}
+--service_ping_jvm_args -Xmx400M -Xms100M
+\end{verbatim}
+
+ Note: When used as a CLI option, the arguments must usually be
+ quoted to protect them from the shell.
+
+ \item[$--$service\_ping\_timeout {[time-in-ms]}] This is the time in
milliseconds to wait for a
+ ping to the service. If the timer expires without a response the ping
is ``failed''. After
+ a certain number of consecutive failed pings, the service is
considered ``down.'' See
+ \hyperref[sec:service.pingers]{Service Pingers} for more details.
+
+ \item[$--$service\_request\_endpoint {[string]}] This specifies the
expected service id.
+
+ This string is optional for UIMA-AS services; if specified, however,
it must be of the
+ form {\tt UIMA-AS:queue:broker-url}, and both the queue and broker
must match those specified in the
+ service DD specifier.
+
+ If the service is CUSTOM, the endpoint is required, and must be of the
form
+ {\tt CUSTOM:string} where the contents of the string are determined by
the service.
+
+ \item[$--$specification, $-$f {[file]}] All the parameters used to
submit a service may be placed in a
+ standard Java properties file. This file may then be used to submit
the service (rather than
+ providing all the parameters directory to submit).
+ For example,
+
+\begin{verbatim}
+ducc_service_submit --specification svc.props
+ducc_service_submit -f svc.props
+\end{verbatim}
+
+ where the svc.props contains:
+
+\begin{verbatim}
+environment = AE_INIT_TIME=5000 AE_INIT_RANGE=1000 INIT_ERROR=0
+description = Test Service 3
+jvm_args = -DdefaultBrokerURL=tcp://agent86:61616
+classpath = /home/bob/lib/app.jar
+process_memory_size = 15
+working_directory = /home/bob/services
+process_DD = /home/bob/services/service.xml
+scheduling_class = fixed
+service_dependency = UIMA-AS:FixedSleepAE_4:tcp://agent86:61616
+\end{verbatim}
+
+ \item[$--$working\_directory {[directory-name]}]
+ This specifies the working directory to be set by the Job Driver and
Job Process processes.
+ If not specified, the current directory is used.
+ \end{description}
+
\subsection{ducc\_services --start Options}
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-uguide.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-uguide.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-uguide.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-uguide.tex
Thu Jun 27 17:06:28 2013
@@ -98,8 +98,9 @@ ducc_job_submit --specification 1.job --
% \input{part2/cli/ducc-monitor.tex}
\input{part2/cli/ducc-reserve.tex}
\input{part2/cli/ducc-unreserve.tex}
- \input{part2/cli/ducc-service-submit.tex}
- \input{part2/cli/ducc-service-cancel.tex}
+ % service submit/cancel not part of the public CLI/API
+ % \input{part2/cli/ducc-service-submit.tex}
+ % \input{part2/cli/ducc-service-cancel.tex}
\input{part2/cli/ducc-process-submit.tex}
\input{part2/cli/ducc-process-cancel.tex}
\input{part2/cli/ducc-services.tex}
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-properties.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-properties.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-properties.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-properties.tex
Thu Jun 27 17:06:28 2013
@@ -1278,10 +1278,17 @@
\item[ducc.agent.launcher.cgroups.enable] \hfill \\
- \phantomsection\label{itm:props-agent.cgroups.enable}
- Enable or disable CGroups support.
+ \phantomsection\label{itm:props-agent.cgroups.enable} Enable or
disable CGroups support.
+ If CGroups are not installed on a specific machine, this is
ignored.
+
+ With CGroups the RSS for a managed process (plus any children
processes it may spawn) is
+ limited to the allocated share size. Additional memory use goes to
swap space. DUCC
+ monitors and limits swap use to the same proportion of total swap
space as allocated
+ share size is to total RAM. If a process exceeds its allowed swap
space it is terminated
+ and a ShareSizeExceeded message is sent to the Job Driver.
+
+ Nodes not using CGroups fall back to the
ducc.agent.share.size.fudge.factor.
- If CGroups are not installed on a specific machine, this is
ignored.
\begin{description}
\item[Default Value] true
\item[Type] Tuning
@@ -1406,7 +1413,7 @@
\item[ducc.uima-as.dd2spring.xsl.path] \hfill \\
This configures the path the required dd2spring xsl definitions.
\begin{description}
- \item[Default Value] \$\{DUCC\_HOME}/resources/dd2sprint.xsl
+ \item[Default Value] \$\{DUCC\_HOME\}/resources/dd2sprint.xsl
\item[Type] Private
\end{description}
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-ws-security.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-ws-security.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-ws-security.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/admin/ducc-ws-security.tex
Thu Jun 27 17:06:28 2013
@@ -12,7 +12,8 @@
\begin{enumerate}
\item Author an authentication manager Java class implementing interface
\begin{verbatim}
-org.apache.uima.ducc.common.authentication.IAuthenticationManager\end{verbatim}
+org.apache.uima.ducc.common.authentication.IAuthenticationManager
+ \end{verbatim}
\item Create an authentication jar file comprising the
authentication manager Java class
\item Install your authentication jar file and any dependency jar files
@@ -20,8 +21,8 @@ org.apache.uima.ducc.common.authenticati
\item Update your ducc.properties file with authentication class name
and jar file name(s) information
\item Create a ducc.administrators file
- \end{enumerate}
-
+ \end{enumerate}
+
Note: When a user clicks on the WebServer Login link, the login dialog is
shown. On that dialog panel is shown the \mbox{authenticator: {\em
version}}, which is supplied by your authentication manager
implementation's {\em
@@ -31,7 +32,6 @@ org.apache.uima.ducc.common.authenticati
disabled.
\subsection{Example Implementation}
- \begin{description}
Shown below is an example implementation which can be used as a template
for coding protection by means of interfacing with your site's security
@@ -96,10 +96,8 @@ public class AuthenticationManager imple
}
\end{verbatim}
- \end{description}
\subsection{IAuthenticationManager}
- \begin{description}
Shown below is the interface which must be implemented by your
authentication manager.
@@ -158,10 +156,9 @@ public interface IAuthenticationManager
}
}
\end{verbatim}
- \end{description}
+
\subsection{IAuthenticationResult}
- \begin{description}
Shown below is the interface which must be returned by the required
authentication methods in your authentication manager.
@@ -182,10 +179,8 @@ public interface IAuthenticationResult {
public Exception getException();
}
\end{verbatim}
- \end{description}
\subsection{Example ANT script to build jar}
- \begin{description}
Shown below is an example ANT script to build a ducc-authenticator.jar
file.
The resulting jar file should be placed user DUCC's lib directory along
with
@@ -210,10 +205,8 @@ public interface IAuthenticationResult {
</project>
\end{verbatim}
- \end{description}
\subsection{Example ducc.properties entries}
- \begin{description}
Shown here is a snippet of the ducc.properties file defining the class to
be
used for authentication and the administrator created folder
@@ -225,15 +218,13 @@ public interface IAuthenticationResult {
\begin{verbatim}
# The class that performs authentication (for the WebServer)
-org.apache.uima.ducc.example.authentication.module.AuthenticationManager
+ducc.authentication.implementer =
org.apache.uima.ducc.example.authentication.module.AuthenticationManager
# Site specific jars: include all jars in directory site-security
ducc.local.jars = site-security/*
\end{verbatim}
- \end{description}
\subsection{Example ducc.administrators}
- \begin{description}
Example contents of ducc.administrators file located within DUCC's
resources
directory. Only userids listed here can assume the Administrator role when
@@ -244,4 +235,6 @@ jdoe
fred
hal9000
\end{verbatim}
- \end{description}
\ No newline at end of file
+
+
+
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/install.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/install.tex?rev=1497449&r1=1497448&r2=1497449&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/install.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part4/install.tex
Thu Jun 27 17:06:28 2013
@@ -25,12 +25,14 @@ trunk/target directory. The distribution
where [version] is the DUCC version; for example, {\em \distro}. This
document will refer to the distribution
file as the ``$<$distribution.file$>$''.
-\subsection{Software Prerequisites}
+\section{Software Prerequisites}
+\label{sec:install.prerequisites}
Both single and multi-user configurations have the following software
pre-requisites:
\begin{itemize}
\item A userid {\em ducc}, and group {\em ducc}. User {\em ducc} must the
the only member of group {\em ducc}.
- \item Reasonably current Linux. DUCC has been tested on SUSE Linux
distributions.
+ \item Reasonably current Linux. DUCC has been tested on SLES 10.2, 11.1,
and 11.2, and RHEL 6.3.
+ \item For CGroupt support, libcgroup1-0.37+ on SLES and libcgroup-0.37+ on
RHEL.
\item IBM or Oracle Java JRE 1.6 or greater.
\item Python 2.x, where 'x' is 4 or greater. DUCC has not been tested on
Python 3.x.
\end{itemize}
@@ -64,7 +66,7 @@ To build the documentation, the followin
More detailed one-time setup instructions for source-level builds via
subversion can be found here:
\url{http://uima.apache.org/one-time-setup.html\#svn-setup}
-\subsection{Documentation}
+\section{Documentation}
After single-user installation, the DUCC documentation is found (in both PDF
and HTML format) in the directory
ducc\_runtime/docs. As well, the DUCC web server contains a link to the full
documentation on each major page.
The API is documented only via JavaDoc, distributed in the web server's root
directory
@@ -76,7 +78,7 @@ If building from source, Maven places th
\item {\tt trunk/site/apidocs} (API Javadoc)
\end{itemize}
-\subsection{Single-user Installation and Verification}
+\section{Single-user Installation and Verification}
Single-user installation sets up an initial, working configuration on a single
system. No security
is established, and all jobs run as user ducc. Note that all installation
must be done as user ducc.
@@ -85,7 +87,7 @@ Verification submits a very simple UIMA
working, one may proceed to upgrade to full installation.
-\subsection{Minimal Hardware Requirements for single-user Installation}
+\section{Minimal Hardware Requirements for single-user Installation}
\begin{itemize}
\item One Intel-based or IBM Power-based system. (More systems may be
added during multi-user
installation, described below.)
@@ -102,7 +104,7 @@ clusters consisting of multiple nodes wi
requirements are for initial test and evaluation purposes, but will not be
sufficient to run actual
workloads.
-\subsection{Single-user System Installation}
+\section{Single-user System Installation}
\label{subsec:install.single-user}
\begin{enumerate}
\item Expand the distribution file:
@@ -162,7 +164,7 @@ The post-installation script performs th
\item Insures that the (supplied) ActiveMQ broker is runnable.
\end{enumerate}
-\subsection{Initial System Verification}
+\section{Initial System Verification}
Here we start the basic installation, submit a simple UIMA-AS job, verify that
it ran, and stop
DUCC. Once this is confirmed working DUCC is ready to use in an unsecured,
single-user mode on a
@@ -264,7 +266,7 @@ $HOME/ducc/logs/job-id
Installation and Verification to set up multiple-user support and
optionally, multi-node
operation.
-\subsection{Logs}
+\section{Logs}
The DUCC system logs are written to the directory
\begin{verbatim}
ducc_runtime/logs
@@ -278,13 +280,15 @@ $HOME/ducc/logs/job-id
$HOME/ducc/logs/<jobid>
\end{verbatim}
-\subsection{Multi-User Installation and Verification}
+\section{Multi-User Installation and Verification}
- Multi-user installation consists of two steps over and above single-user
installation:
+ Multi-user installation consists of these steps over and above single-user
installation:
\begin{enumerate}
\item Install and configure the setuid-root program, ducc\_ling. This
small program allows DUCC
jobs to be run as the submitting user rather than user ducc.
+ \item Optionally install and configure CGroups.
+
\item Optionally update the configuration to include additional nodes.
\end{enumerate}
@@ -302,7 +306,7 @@ $HOME/ducc/logs/job-id
\item Root access is (briefly) required to install a small
setuid-root program on each system.
\end{itemize}
-\subsection{Ducc\_ling Installation}
+\section{Ducc\_ling Installation}
Before proceeding with this step, please note:
\begin{itemize}
\item This step is required ONLY to install multi-user capabilities.
@@ -392,19 +396,67 @@ ducc.agent.launcher.ducc\_spawn\_path=/l
prevent the LD\_LIBRARY\_PATH from being set by a program with root
authority, so this is
done AFTER changing userids).
\end{itemize}
-
-\subsection{Set up the full nodelists}
-To add additional nodes to the ducc cluster, DUCC needs to know what nodes to
start its Agent
-processes on. These nodes are listed in the file
+
+\section{CGroups Installation and Configuration}
+ The steps in this task must all be done as user root.
+
+ To install and configure CGroups for DUCC:
+ \begin{enumerate}
+ \item Install the appropriate
\hyperref[sec:install.prerequisites]{libcgroup package} at level 0.37
+ or above.
+
+ \item Configure /etc/cgconfig.conf as follows:
\begin{verbatim}
-ducc_runtime/resources/ducc.nodes.
+ # Mount cgroups
+ mount {
+ memory = /cgroup;
+ }
+ # Define cgroup ducc and setup permissions
+ group ducc {
+ perm {
+ task {
+ uid = ducc;
+ }
+ admin {
+ uid = ducc;
+ }
+ }
+ memory {}
+ }
+\end{verbatim}
+ \item Start the cgconfig service:
+\begin{verbatim}
+ service cgconfig start
+\end{verbatim}
+
+ \item Verify cgconfig service is running by the existence of directory:
+\begin{verbatim}
+ /cgroups/ducc
+\end{verbatim}
+
+ \item Configure the cgconfig service to start on reboot:
+\begin{verbatim}
+ chkconfig cgconfig on
\end{verbatim}
-During initial installation, this file was initialized with the node DUCC is
installed on.
-Additional nodes may be added to the file using a text editor to increase the
size of the DUCC
-cluster.
+ \item Update \hyperref[itm:props-agent.cgroups.enable]{ducc.properties}
to enable CGroups.
+ Note that if CGroups is not installed, the DUCC Agent will detect
this and not attempt to
+ use the feature. It is completely safe to enable CGroups in {\em
ducc.properties} on
+ machines where it is not installed.
+ \end{enumerate}
-\subsection{Full DUCC Verification}
+\section{Set up the full nodelists}
+ To add additional nodes to the ducc cluster, DUCC needs to know what nodes
to start its Agent
+ processes on. These nodes are listed in the file
+\begin{verbatim}
+ducc_runtime/resources/ducc.nodes.
+\end{verbatim}
+
+ During initial installation, this file was initialized with the node DUCC
is installed on.
+ Additional nodes may be added to the file using a text editor to increase
the size of the DUCC
+ cluster.
+
+\section{Full DUCC Verification}
This is identical to initial verification, with the one difference that the
job ``1.job'' should be
submitted as any user other than ducc. Watch the webserver and insure that
you see the job execute
